Billing
Newest-first history for the caller: prepaid-credit movements (purchases, project charges, adjustments, expiry, refunds) from the append-only ledger, plus subscription plan changes. RLS-scoped to the caller's account.
BearerAuthAuthorizationBearer <token>JWT access token. Obtain via POST /v1/auth/login.
Successful Response
application/json- response
[index: integer]?curl -X GET 'https://api.aisc.sa/v1/billing/me/billing/history'[ { "at": "2019-08-24T14:15:22Z", "credits": 0, "detail": "string", "kind": "string" }]Returns the account's spendable prepaid PAYG credit balance (1 credit = 1 project). Credits are consumed by the project-as-unit charge only after the plan quota is exhausted; a zero balance is normal for a subscription still inside its pooled quota.
BearerAuthAuthorizationBearer <token>JWT access token. Obtain via POST /v1/auth/login.
Successful Response
application/json- response
balance*BalancePrepaid PAYG credit balance for the account (1 credit = 1 project).
curl -X GET 'https://api.aisc.sa/v1/billing/me/credits'{ "balance": 3}Records a pending credit-pack purchase and (when StreamPay is provisioned) returns a hosted-checkout URL. Credits are granted ONLY after the payment is verified server-side by the webhook — the client never sets the amount or the balance.
BearerAuthAuthorizationBearer <token>JWT access token. Obtain via POST /v1/auth/login.
application/json- body
customer_email?|nullcustomer_name?|nullcustomer_phone?|nullpack*PackCredit pack: 'standalone' (1 credit, SAR 449) or 'pack_10' (10 credits, SAR 3,990).
"standalone""pack_10"Successful Response
application/json- response
amount_sar*Amount Sar^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$checkout_url?|StreamPay hosted-checkout URL to redirect the buyer to. None while STREAMPAY_X_API_KEY is unprovisioned — the pending purchase is still recorded and will be credited once the verified payment webhook arrives.
credits*Creditspack*Packpurchase_id*Purchase Iduuidcurl -X POST 'https://api.aisc.sa/v1/billing/me/credits/purchase' \ -H 'Content-Type: application/json' \ -d '{ "pack": "standalone"}'{ "amount_sar": "string", "checkout_url": "string", "credits": 0, "pack": "string", "purchase_id": "06b23ec9-3221-4327-b592-c31d5c56b2f8"}Returns the TRUE state of a credit purchase for the success page. Security: the status is read from the DB (RLS-scoped to the caller) and, while still uncredited, reconciled against a live StreamPay fetch of the payment link — NEVER from the URL. Changing the purchase id only ever returns that purchase's real state (404 if it isn't the caller's); an unpaid purchase can never read as 'credited'. Idempotent: reconciliation credits at most once.
BearerAuthAuthorizationBearer <token>JWT access token. Obtain via POST /v1/auth/login.
purchase_id*Purchase IduuidSuccessful Response
application/json- response
amount_sar*Amount Sar^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$credits*Creditspurchase_id*Purchase Iduuidstatus*Status'credited' only when the payment is server-verified and the credits are in the ledger; 'pending' otherwise. Derived from the DB + a live StreamPay re-fetch — never from the URL — so it cannot be spoofed.
"credited""pending"curl -X GET 'https://api.aisc.sa/v1/billing/me/credits/purchases/497f6eca-6276-4993-bfeb-53cbbbba6f08'{ "amount_sar": "string", "credits": 0, "purchase_id": "06b23ec9-3221-4327-b592-c31d5c56b2f8", "status": "credited"}The metered chokepoint for private-KB ingestion. Rasterising a PDF and reading every page with a vision model is the most token-hungry thing the platform does per unit of input, so it costs prepaid credits: one credit per 50 pages, rounded up, minimum one. Idempotent on document_sha, so a retry or a re-run after a failed parse is free. Returns 402 when the balance cannot cover the document. Call this BEFORE the vision pass — charging afterwards either gives away the expensive part or bills for a failure.
BearerAuthAuthorizationBearer <token>JWT access token. Obtain via POST /v1/auth/login.
application/json- body
One private-knowledge document about to be read by the vision model.
document_sha*Document Sha16 <= length <= 128pages*Pages1 <= value <= 2000Successful Response
application/json- response
already_charged*Already Chargedbalance*Balancecharged*Chargedcredits*Creditscurl -X POST 'https://api.aisc.sa/v1/billing/me/knowledge/consume' \ -H 'Content-Type: application/json' \ -d '{ "document_sha": "stringstringstri", "pages": 1}'{ "already_charged": true, "balance": 0, "charged": true, "credits": 0}The metered chokepoint for a compliance analysis run. Charges the account ONCE per plot_key (first run); a rerun of the same plot returns already_charged=true and costs nothing. Precedence: plan quota -> prepaid credit -> overflow. Returns 402 when the quota/credit is exhausted so the caller can prompt an upgrade or a credit purchase. Call this BEFORE running the evaluation so an out-of-quota account is stopped up front.
BearerAuthAuthorizationBearer <token>JWT access token. Obtain via POST /v1/auth/login.
application/json- body
plot_key*Plot KeyStable identifier for the plot/drawing being analysed (survey number, or a per-drawing key like its content hash). The charge is applied ONCE per plot_key — reruns of the same plot are free.
1 <= length <= 200Successful Response
application/json- response
already_charged*Already ChargedTrue if the plot was already charged (free rerun).
charge_version?|nullcharged*ChargedTrue if this call applied a NEW charge.
funding_source?|plan_quota | payg_credit | overflow — how the charge was funded.
plot_key*Plot Keyprojects_billing_id?|The handle needed to RELEASE this charge if the analysis then fails. BILL-LOSS-01: without it a caller could charge but never compensate, which is why a web-path run lost to a restart was billed and never refunded.
curl -X POST 'https://api.aisc.sa/v1/billing/me/projects/consume' \ -H 'Content-Type: application/json' \ -d '{ "plot_key": "string"}'{ "already_charged": true, "charge_version": "2019-08-24T14:15:22Z", "charged": true, "funding_source": "string", "plot_key": "string", "projects_billing_id": "24e2f359-30a5-4ccd-9e22-2f1e250cd250"}Dry-run eligibility (NO charge): does the account have plan quota, prepaid credit, or overflow to fund one more project? The web calls this BEFORE accepting an upload so an out-of-quota user is told up front instead of after processing. Lazily provisions the FREE floor so a new account isn't blocked. Blocked (allowed=false) when the enterprise workspace is not yet activated (reason=pending_activation) or the caller is a read-only Viewer (reason=viewer_read_only).
BearerAuthAuthorizationBearer <token>JWT access token. Obtain via POST /v1/auth/login.
Successful Response
application/json- response
allowed*AllowedCan the account fund one more project analysis?
reason?|When not allowed: pending_activation | viewer_read_only | free_hard_cap | payg_not_opted_in | quota_exhausted | subscription_inactive.
curl -X GET 'https://api.aisc.sa/v1/billing/me/projects/eligibility'{ "allowed": true, "reason": "string"}A failed run must not burn a project or a credit. Reverses the funding decrement and un-marks the project. Idempotent on projects_billing_id: calling it twice grants at most one compensation, so a retrying caller cannot mint quota. 204 when the customer is left uncharged; 409 when nothing was reversed (logged for reconciliation).
BearerAuthAuthorizationBearer <token>JWT access token. Obtain via POST /v1/auth/login.
application/json- body
charge_version?|nullprojects_billing_id*Projects Billing IdThe handle returned by the consume call that charged this run.
uuidSuccessful Response
curl -X POST 'https://api.aisc.sa/v1/billing/me/projects/release' \ -H 'Content-Type: application/json' \ -d '{ "projects_billing_id": "24e2f359-30a5-4ccd-9e22-2f1e250cd250"}'Returns the active subscription row for the authenticated user; scoped by RLS to the caller's tenant. Returns 404 if the caller has no subscription yet (e.g. new sign-up before selecting a plan).
BearerAuthAuthorizationBearer <token>JWT access token. Obtain via POST /v1/auth/login.
Successful Response
application/json- response
billing_cadence*Billing Cadencebilling_mode*Billing Modecancel_at_period_end*Cancel At Period Endcheckout_url?|StreamPay hosted-checkout redirect URL for the sign-up invoice. None for Free plans, Enterprise custom-cadence contracts (negotiated out-of-band), or while STREAMPAY_X_API_KEY is not yet provisioned -- the subscription is still created in these cases, just without a payment link yet.
commitment_end_at*|nullcurrent_period_end*|nullcurrent_period_start*Current Period Startdate-timeid*Iduuidpayer_organisation_id*|nullpayer_user_id*|nullpayg_monthly_ceiling_sar*|nullpayg_opted_in*Payg Opted Inplan_code*Plan Codestatus*Statususer_id*User Iduuidcurl -X GET 'https://api.aisc.sa/v1/billing/me/subscription'{ "billing_cadence": "string", "billing_mode": "string", "cancel_at_period_end": true, "checkout_url": "string", "commitment_end_at": "2019-08-24T14:15:22Z", "current_period_end": "2019-08-24T14:15:22Z", "current_period_start": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "payer_organisation_id": "bcdc3b4b-4432-4c47-b44c-52932b3bf47e", "payer_user_id": "295f0b28-ae85-4d57-93b3-e87e18f208b4", "payg_monthly_ceiling_sar": "string", "payg_opted_in": true, "plan_code": "string", "status": "string", "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"}Creates the caller's subscription, or CHANGES the plan of an existing live one (upgrade or downgrade) — every account has an auto-provisioned FREE subscription, so this is an upsert, not create-only. Accepts plan_code, billing_mode, billing_cadence, and optional PAYG settings.
Moving OFF a paid recurring plan cancels the StreamPay subscription first, so the card stops being auto-charged. Switching TO a paid plan returns a checkout_url (the row stays 'pending' until the payment webhook activates it); switching to FREE activates immediately. Returns 404 if plan_code is unknown.
BearerAuthAuthorizationBearer <token>JWT access token. Obtain via POST /v1/auth/login.
application/json- body
POST /me/subscription body.
billing_cadence*BillingCadence'monthly' or 'annual' for Free/Pro; 'custom' only valid on Enterprise (terms set in the contract).
"monthly""annual""custom"billing_mode*BillingMode'self_pay' charges the user directly; 'org_pay' rolls into the specified organisation's consolidated invoice.
"self_pay""org_pay"payer_organisation_id?|REQUIRED when billing_mode='org_pay'. The organisation whose admin pays the invoice. Caller must be a member; RLS enforces.
payg_monthly_ceiling_sar?||Monthly PAYG ceiling in SAR. Required when payg_opted_in=true; above this projected charge the next consume_*() call rejects.
payg_opted_in?Payg Opted InOpt into PAYG at sign-up. Only valid when the chosen plan supports PAYG (Pro / Enterprise).
falseplan_code*PlanCodeOne of 'free' / 'pro' / 'enterprise'.
"free""pro""enterprise"Successful Response
application/json- response
billing_cadence*Billing Cadencebilling_mode*Billing Modecancel_at_period_end*Cancel At Period Endcheckout_url?|StreamPay hosted-checkout redirect URL for the sign-up invoice. None for Free plans, Enterprise custom-cadence contracts (negotiated out-of-band), or while STREAMPAY_X_API_KEY is not yet provisioned -- the subscription is still created in these cases, just without a payment link yet.
commitment_end_at*|nullcurrent_period_end*|nullcurrent_period_start*Current Period Startdate-timeid*Iduuidpayer_organisation_id*|nullpayer_user_id*|nullpayg_monthly_ceiling_sar*|nullpayg_opted_in*Payg Opted Inplan_code*Plan Codestatus*Statususer_id*User Iduuidcurl -X POST 'https://api.aisc.sa/v1/billing/me/subscription' \ -H 'Content-Type: application/json' \ -d '{ "billing_cadence": "monthly", "billing_mode": "self_pay", "plan_code": "free"}'{ "billing_cadence": "string", "billing_mode": "string", "cancel_at_period_end": true, "checkout_url": "string", "commitment_end_at": "2019-08-24T14:15:22Z", "current_period_end": "2019-08-24T14:15:22Z", "current_period_start": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "payer_organisation_id": "bcdc3b4b-4432-4c47-b44c-52932b3bf47e", "payer_user_id": "295f0b28-ae85-4d57-93b3-e87e18f208b4", "payg_monthly_ceiling_sar": "string", "payg_opted_in": true, "plan_code": "string", "status": "string", "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"}Sets cancel_at_period_end=true. The subscription remains 'active' until current_period_end, at which point a renewal worker transitions it to 'expired'. Returns the updated subscription state.
Enterprise commitments: cancellation BEFORE commitment_end_at is forbidden via this endpoint -- contact support for negotiated early termination.
BearerAuthAuthorizationBearer <token>JWT access token. Obtain via POST /v1/auth/login.
Successful Response
application/json- response
billing_cadence*Billing Cadencebilling_mode*Billing Modecancel_at_period_end*Cancel At Period Endcheckout_url?|StreamPay hosted-checkout redirect URL for the sign-up invoice. None for Free plans, Enterprise custom-cadence contracts (negotiated out-of-band), or while STREAMPAY_X_API_KEY is not yet provisioned -- the subscription is still created in these cases, just without a payment link yet.
commitment_end_at*|nullcurrent_period_end*|nullcurrent_period_start*Current Period Startdate-timeid*Iduuidpayer_organisation_id*|nullpayer_user_id*|nullpayg_monthly_ceiling_sar*|nullpayg_opted_in*Payg Opted Inplan_code*Plan Codestatus*Statususer_id*User Iduuidcurl -X DELETE 'https://api.aisc.sa/v1/billing/me/subscription'{ "billing_cadence": "string", "billing_mode": "string", "cancel_at_period_end": true, "checkout_url": "string", "commitment_end_at": "2019-08-24T14:15:22Z", "current_period_end": "2019-08-24T14:15:22Z", "current_period_start": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "payer_organisation_id": "bcdc3b4b-4432-4c47-b44c-52932b3bf47e", "payer_user_id": "295f0b28-ae85-4d57-93b3-e87e18f208b4", "payg_monthly_ceiling_sar": "string", "payg_opted_in": true, "plan_code": "string", "status": "string", "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"}Enables or disables pay-as-you-go metered billing for the caller's subscription and optionally sets a monthly SAR ceiling. When opting out, the ceiling is cleared server-side. Returns 422 if the plan does not support PAYG; returns 404 if no subscription exists.
BearerAuthAuthorizationBearer <token>JWT access token. Obtain via POST /v1/auth/login.
application/json- body
PATCH /me/subscription/payg body.
payg_monthly_ceiling_sar?||nullpayg_opted_in*Payg Opted InSuccessful Response
application/json- response
billing_cadence*Billing Cadencebilling_mode*Billing Modecancel_at_period_end*Cancel At Period Endcheckout_url?|StreamPay hosted-checkout redirect URL for the sign-up invoice. None for Free plans, Enterprise custom-cadence contracts (negotiated out-of-band), or while STREAMPAY_X_API_KEY is not yet provisioned -- the subscription is still created in these cases, just without a payment link yet.
commitment_end_at*|nullcurrent_period_end*|nullcurrent_period_start*Current Period Startdate-timeid*Iduuidpayer_organisation_id*|nullpayer_user_id*|nullpayg_monthly_ceiling_sar*|nullpayg_opted_in*Payg Opted Inplan_code*Plan Codestatus*Statususer_id*User Iduuidcurl -X PATCH 'https://api.aisc.sa/v1/billing/me/subscription/payg' \ -H 'Content-Type: application/json' \ -d '{ "payg_opted_in": true}'{ "billing_cadence": "string", "billing_mode": "string", "cancel_at_period_end": true, "checkout_url": "string", "commitment_end_at": "2019-08-24T14:15:22Z", "current_period_end": "2019-08-24T14:15:22Z", "current_period_start": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "payer_organisation_id": "bcdc3b4b-4432-4c47-b44c-52932b3bf47e", "payer_user_id": "295f0b28-ae85-4d57-93b3-e87e18f208b4", "payg_monthly_ceiling_sar": "string", "payg_opted_in": true, "plan_code": "string", "status": "string", "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"}Reverses a prior soft-cancel by clearing cancel_at_period_end. Only valid while the subscription is still 'active' and before current_period_end. Returns 404 if no subscription exists, 409 if the subscription is already expired or the state transition is illegal.
BearerAuthAuthorizationBearer <token>JWT access token. Obtain via POST /v1/auth/login.
Successful Response
application/json- response
billing_cadence*Billing Cadencebilling_mode*Billing Modecancel_at_period_end*Cancel At Period Endcheckout_url?|StreamPay hosted-checkout redirect URL for the sign-up invoice. None for Free plans, Enterprise custom-cadence contracts (negotiated out-of-band), or while STREAMPAY_X_API_KEY is not yet provisioned -- the subscription is still created in these cases, just without a payment link yet.
commitment_end_at*|nullcurrent_period_end*|nullcurrent_period_start*Current Period Startdate-timeid*Iduuidpayer_organisation_id*|nullpayer_user_id*|nullpayg_monthly_ceiling_sar*|nullpayg_opted_in*Payg Opted Inplan_code*Plan Codestatus*Statususer_id*User Iduuidcurl -X POST 'https://api.aisc.sa/v1/billing/me/subscription/reactivate'{ "billing_cadence": "string", "billing_mode": "string", "cancel_at_period_end": true, "checkout_url": "string", "commitment_end_at": "2019-08-24T14:15:22Z", "current_period_end": "2019-08-24T14:15:22Z", "current_period_start": "2019-08-24T14:15:22Z", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "payer_organisation_id": "bcdc3b4b-4432-4c47-b44c-52932b3bf47e", "payer_user_id": "295f0b28-ae85-4d57-93b3-e87e18f208b4", "payg_monthly_ceiling_sar": "string", "payg_opted_in": true, "plan_code": "string", "status": "string", "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"}Returns a snapshot of the caller's billing.usage_meters row covering the present moment. Useful for in-app dashboards showing 'X reviews remaining', 'Y GB used', running PAYG charges, etc. Returns 404 if the caller has no active subscription (and therefore no current meter).
BearerAuthAuthorizationBearer <token>JWT access token. Obtain via POST /v1/auth/login.
Successful Response
application/json- response
compliance_reviews_payg_count*Compliance Reviews Payg Countcompliance_reviews_used*Compliance Reviews Usedgenerative_tokens_payg*Generative Tokens Payggenerative_tokens_used*Generative Tokens Usedpayg_charges_sar*Payg Charges Sar^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$period_end*Period Enddate-timeperiod_start*Period Startdate-timestorage_gb_payg*Storage Gb Payg^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$storage_gb_used*Storage Gb Used^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$webhook_deliveries_payg*Webhook Deliveries Paygwebhook_deliveries_used*Webhook Deliveries Usedcurl -X GET 'https://api.aisc.sa/v1/billing/me/usage'{ "compliance_reviews_payg_count": 0, "compliance_reviews_used": 0, "generative_tokens_payg": 0, "generative_tokens_used": 0, "payg_charges_sar": "string", "period_end": "2019-08-24T14:15:22Z", "period_start": "2019-08-24T14:15:22Z", "storage_gb_payg": "string", "storage_gb_used": "string", "webhook_deliveries_payg": 0, "webhook_deliveries_used": 0}Returns the public plan catalog ordered Free -> Pro -> Enterprise. All authenticated users see the same list (catalog is not RLS-scoped). Useful for billing UI: render the pricing page from this response.
BearerAuthAuthorizationBearer <token>JWT access token. Obtain via POST /v1/auth/login.
Successful Response
application/json- response
[index: integer]?A row from billing.plans, transmitted over the wire.
curl -X GET 'https://api.aisc.sa/v1/billing/plans'[ { "annual_price_sar": "string", "annual_total_sar": "string", "audit_retention_days": 0, "billing_cadence": "string", "code": "string", "compliance_review_payg_unit_price_sar": "string", "compliance_reviews_per_month": 0, "display_name": "string", "generative_token_payg_unit_price_sar_per_1k": "string", "includes_cultural_overlay": true, "max_webhook_deliveries_per_month": 0, "max_webhook_subscriptions": 0, "min_commitment_months": 0, "monthly_price_sar": "string", "payg_default_ceiling_sar": "string", "pdf_branding": "string", "storage_gb_included": 0, "storage_payg_unit_price_sar": "string", "supports_org_pay": true, "supports_payg": true, "supports_self_pay": true }]Returns the full billing.plans row for a single plan identified by its code (e.g. 'free', 'pro', 'enterprise'). Useful for building plan-detail or upgrade-confirmation screens. Returns 404 if the plan code is unknown.
BearerAuthAuthorizationBearer <token>JWT access token. Obtain via POST /v1/auth/login.
plan_code*PlanCode"free""pro""enterprise"Successful Response
application/json- response
A row from billing.plans, transmitted over the wire.
annual_price_sar*|nullannual_total_sar?|What one seat is charged per year on the annual cadence: the invoice figure, paid once a year. annual_price_sar is only its per-month equivalent. NULL when the plan has no annual price (Free, Enterprise).
audit_retention_days*Audit Retention Daysbilling_cadence*Billing Cadencecode*Codecompliance_review_payg_unit_price_sar?|NULL on hard-cap plans (Free)
compliance_reviews_per_month?|NULL = unlimited (Enterprise)
display_name*Display Namegenerative_token_payg_unit_price_sar_per_1k*|nullincludes_cultural_overlay*Includes Cultural Overlaymax_webhook_deliveries_per_month*integer|nullmax_webhook_subscriptions*integer|nullmin_commitment_months*Min Commitment Monthsmonthly_price_sar*|nullpayg_default_ceiling_sar*|nullpdf_branding*Pdf Brandingstorage_gb_included*integer|nullstorage_payg_unit_price_sar*|nullsupports_org_pay*Supports Org Paysupports_payg*Supports Paygsupports_self_pay*Supports Self Paycurl -X GET 'https://api.aisc.sa/v1/billing/plans/free'{ "annual_price_sar": "string", "annual_total_sar": "string", "audit_retention_days": 0, "billing_cadence": "string", "code": "string", "compliance_review_payg_unit_price_sar": "string", "compliance_reviews_per_month": 0, "display_name": "string", "generative_token_payg_unit_price_sar_per_1k": "string", "includes_cultural_overlay": true, "max_webhook_deliveries_per_month": 0, "max_webhook_subscriptions": 0, "min_commitment_months": 0, "monthly_price_sar": "string", "payg_default_ceiling_sar": "string", "pdf_branding": "string", "storage_gb_included": 0, "storage_payg_unit_price_sar": "string", "supports_org_pay": true, "supports_payg": true, "supports_self_pay": true}