# Kyber Billing API (https://billing.kyberapps.com)

Billing portal for Kyber Systems LLC: brands KyberApps (umbrella), KyberGate, KyberAccess, KyberWatch, KyberCopy; one Stripe account per brand group (Kyber Systems, KyberAccess, KyberGate). JSON API at /api/v1. Authenticate with `Authorization: Bearer kb_...` (token created by the admin in Settings, scoped). All money is integer cents, USD. Send `Idempotency-Key` on POST creates. Rate limit per token: 60 burst, 1/s sustained (429 with Retry-After).

Flow: create org -> create quote (lines by product) -> POST /quotes/{id}/send (returns share_url for /q/<token>) -> POST /proposals {quote_id} (returns share_url for /p/<token>, customer accepts there) -> GET /proposals/{id}/status -> POST /invoices {proposal_id} (Stripe) or {proposal_id, manual:true} (PO/check), or POST /subscriptions {proposal_id} for annual auto-renewing plans.

Brands: every org/quote/proposal/invoice/subscription/payment link has brand (kyberapps|kybergate|kyberaccess|kyberwatch|kybercopy|unassigned) and account_id (Stripe account). Filter any list with ?brand= and ?account=<label>. Quotes accept brand, billing_mode (invoice|subscription) and account_id; defaults come from the line products and the brand's Stripe account. GET /stripe-accounts lists accounts (no keys). GET /dashboard gives MRR/ARR per brand and per account.

Pricing rules (GET /pricing-rules): KyberCopy flat annual per campus by enrollment: Small <500 $1,800; Standard 500-1,500 $3,600; Large 1,500-4,000 $6,000; District 4,000+ quoted. KyberGate per device per year, floor $5.00, E-Rate eligible. KyberAccess and KyberWatch: manual price required. Pilots: $0 lines with is_pilot=true and a term. Multi-year: 10% (2 yr), 15% (3 yr). No tax (schools, record exemption number).

## Endpoints

- GET /api/v1/me [read]: Who am I. Returns the token label and scopes.
- GET /api/v1/pricing-rules [read]: Pricing rules. The pricing rules as data: KyberCopy bands, KyberGate floor and bands, manual products, multi-year discounts.
- GET /api/v1/pricing-rules/suggest?product=KyberCopy&qty=1&enrollment=900 [read]: Suggest a line. Default description, unit and unit price for a product. requires_price=true means the price must be supplied manually.
- GET /api/v1/terms [read]: Agreement text. Current Master Subscription Agreement text and version.
- GET /api/v1/orgs?search= [read]: List organizations.
- POST /api/v1/orgs [quotes:write]: Create organization. type is school, district or other. contacts is a list of {name,email,phone,role}. products is a list of product names.
  body: {"name": "Sample Academy", "type": "school", "address": "1 Main St, Albany, NY", "enrollment": 900, "contacts": [{"name": "Dana Lee", "email": "dlee@sample.edu", "phone": "", "role": "IT Director"}], "products": ["KyberCopy"], "tax_exempt": true, "tax_exempt_no": "EX-12345"}
- GET /api/v1/orgs/{id} [read]: Get organization. Includes the org's quotes, proposals and invoices.
- PATCH /api/v1/orgs/{id} [quotes:write]: Update organization. Send only the fields you want to change.
  body: {"enrollment": 1200}
- GET /api/v1/quotes?org_id=&status= [read]: List quotes. status: draft, sent, accepted, expired, declined, converted.
- POST /api/v1/quotes [quotes:write]: Create quote. Lines: product (KyberGate, KyberAccess, KyberWatch, KyberCopy), description (optional, defaulted), qty, unit, unit_cents or unit_price (dollars), years, term_start, term_end, is_pilot. KyberCopy price is defaulted from the org's enrollment band when unit_cents is omitted. KyberGate never below 500 cents. KyberAccess and KyberWatch need a manual price. discount_type: none, percent (discount_percent, e.g. 10) or fixed (discount_amount in dollars). multi_year_percent: 0, 10 or 15. valid_until defaults to 30 days.
  body: {"org_id": 1, "lines": [{"product": "KyberCopy", "qty": 1, "term_start": "2026-11-01", "term_end": "2027-10-31"}, {"product": "KyberGate", "qty": 800, "unit_price": "5.50", "description": "KyberGate Basic, per device, annual"}], "discount_type": "percent", "discount_percent": 10, "notes": "Pricing held through the validity date."}
- GET /api/v1/quotes/{id} [read]: Get quote. Includes share_path (/q/<token>) for the customer-facing page.
- PATCH /api/v1/quotes/{id} [quotes:write]: Update quote. Same fields as create. Pass status: declined to decline. Accepted or converted quotes are locked.
  body: {"lines": [{"product": "KyberCopy", "qty": 2, "unit_price": "3600"}]}
- POST /api/v1/quotes/{id}/send [quotes:write]: Mark quote sent. Sets status=sent and returns share_url. Nothing is emailed; deliver the link yourself.
- POST /api/v1/quotes/{id}/duplicate [quotes:write]: Duplicate quote. New draft with a new number.
- GET /api/v1/proposals?org_id=&status= [read]: List proposals.
- POST /api/v1/proposals [proposals:write]: Create proposal from quote. Snapshots the quote and org, drafts the cover letter, attaches the current agreement text. payment_terms: net30 (PO, Stripe send_invoice) or card (hosted invoice, charge automatically). send: true also marks it sent.
  body: {"quote_id": 1, "payment_terms": "net30", "po_number": "", "send": true}
- GET /api/v1/proposals/{id} [read]: Get proposal. Includes share_url and the quote snapshot.
- GET /api/v1/proposals/{id}/status [read]: Proposal status. Acceptance details: accepted_name, accepted_title, accepted_email, accepted_at (UTC), accepted_ip.
- PATCH /api/v1/proposals/{id} [proposals:write]: Update proposal. cover_letter, payment_terms, po_number, term_start, term_end, status (sent/declined). Locked after acceptance.
  body: {"po_number": "PO-2026-118"}
- POST /api/v1/proposals/{id}/send [proposals:write]: Mark proposal sent. Returns share_url. Nothing is emailed.
- GET /api/v1/invoices?org_id=&status= [read]: List invoices. Also returns stripe_connected and stripe_test_mode.
- POST /api/v1/invoices [invoices:write]: Create invoice from accepted proposal. With Stripe connected: creates a draft Stripe invoice from the proposal snapshot (send_invoice net-30 for PO, charge_automatically for card). send: true finalizes and sends it. Without Stripe, or for check/PO tracking, pass manual: true to create a local invoice record (amount defaults to the proposal total).
  body: {"proposal_id": 1, "send": false}
- GET /api/v1/invoices/{id} [read]: Get invoice.
- POST /api/v1/invoices/{id}/send [invoices:write]: Finalize and send Stripe invoice.
- POST /api/v1/invoices/{id}/mark-paid [invoices:write]: Mark paid (check or PO). method: check, ach, po, other. reference: check number or remittance id.
  body: {"method": "check", "reference": "chk 10422"}
- GET /api/v1/subscriptions?org_id=&status=&brand=&account= [read]: List subscriptions. Annual plans mirrored from Stripe, per brand and per Stripe account. amount_cents is the annualised value; next_invoice_at is the renewal date.
- POST /api/v1/subscriptions [subscriptions:write]: Create subscription from accepted proposal. The proposal's quote must have billing_mode=subscription (or pass it anyway to bill an accepted quote annually). Creates the Stripe subscription on the proposal's account (annual, N-year interval for multi-year lines), the first invoice follows Stripe's collection method. Nothing is emailed.
  body: {"proposal_id": 1}
- GET /api/v1/subscriptions/{id} [read]: Get subscription.
- PATCH /api/v1/subscriptions/{id} [subscriptions:write]: Set subscription brand. brand: kyberapps, kybergate, kyberaccess, kyberwatch, kybercopy or unassigned.
  body: {"brand": "kybergate"}
- POST /api/v1/subscriptions/{id}/sync [subscriptions:write]: Sync subscription from Stripe.
- GET /api/v1/payment-links?brand=&account=&org_id= [read]: List payment links.
- POST /api/v1/payment-links [links:write]: Create payment link. Stripe-hosted pay page. account (label) defaults to the brand's account. unit_cents or unit_price; qty; recurring: empty (one-off), month or year; product optional (KyberGate, KyberCopy, ...).
  body: {"brand": "kybergate", "description": "KyberGate \u00b7 1,200 devices \u00b7 2026-27", "unit_price": "6000", "qty": 1, "recurring": "", "org_id": 1}
- GET /api/v1/payment-links/{id} [read]: Get payment link.
- POST /api/v1/payment-links/{id}/deactivate [links:write]: Deactivate payment link.
- POST /api/v1/orgs/{id}/portal [read]: Customer portal session. Short-lived Stripe customer-portal URL for the org (invoice history, payment methods, billing details; cancel is off). account optional.
  body: {"account": "kyber-systems"}
- GET /api/v1/stripe-accounts [read]: List Stripe accounts. Label, Stripe account id, display name, default brand, mode, connected, webhook secret set, last sync. Never returns keys.
- POST /api/v1/stripe-accounts/{id}/sync [admin]: Sync one Stripe account. id is the label or numeric id. full: true also walks products and quotes (the Import existing action). Read-only against Stripe.
  body: {"full": false}
- GET /api/v1/brands [read]: Brands. The five brands (KyberApps umbrella + four products), the payee, and which Stripe account each brand bills from.
- GET /api/v1/dashboard?brand=&account= [read]: Dashboard numbers. MRR, ARR, open, overdue, paid YTD, active subscriptions, pilots: total, per brand and per Stripe account.

OpenAPI: https://billing.kyberapps.com/api/v1/openapi.json
Docs: https://billing.kyberapps.com/docs