Credits

Credits pay for Console checks. The balance endpoint returns balance, spend_cap_cents, and current_month_spend_cents, and is safe to call before submitting a check.

The ledger lists every credit movement, newest first, 50 per page. Pass meta.next_cursor back as cursor for the next page, and filter with reason: purchase, scan_consumption, refund, action_consumption, manual_adjustment, or promotional_grant. Each entry carries id, delta (positive adds credits, negative removes them), reason, scan_id, payment_reference (the order id of a card purchase; refund rows repeat the order id of the purchase they reverse), description (a readable line such as 100 credit pack or Refund: check failed), and created_at. ledger.csv streams the whole ledger with the columns id, created_at, reason, delta, scan_id, payment_reference, and description.

packs returns the active credit packs (pricing_id, credits, price_cents, name, description, badge). To buy credits, use Buy credits in the Console. checkout takes {"pricing_id": <int>}, requires a signed-in member with billing permission who pays for the selected workspace (see Who buys credits), and checks your monthly spend cap. It returns checkout_reference and a hosted checkout_url. Pack prices exclude tax; any tax for your location is added at checkout. While new purchases are paused, checkout returns 503 with service_unavailable. API keys cannot create or recover a checkout; these actions require a session and an explicit X-Workspace-Id header.

Credits become available only after SurfacedBy verifies the paid order against your workspace's checkout. Returning to the Console alone does not add credits. If you closed checkout after paying, use Check payment in Billing. POST /credits/checkout/recover takes {"checkout_reference": "<reference>"} and returns the verified state. GET /credits/checkouts lists your recent attempts in the selected workspace. An unpaid attempt has no recorded payment; pending is awaiting verification; reconciliation and refund_required need support review. Recovery stays available while new purchases are paused.

Pricing is described in Credit model. Preview the cost of a check with the preview operation under Scans.

curl -X GET "https://api.surfacedby.com/api/v1/console/credits/balance" \
  -H "X-API-Key: string"

null

curl -X GET "https://api.surfacedby.com/api/v1/console/credits/ledger?cursor=0&reason=string" \
  -H "X-API-Key: string"

null

curl -X GET "https://api.surfacedby.com/api/v1/console/credits/ledger.csv?reason=string" \
  -H "X-API-Key: string"

null

curl -X GET "https://api.surfacedby.com/api/v1/console/credits/packs" \
  -H "X-API-Key: string"

null

curl -X POST "https://api.surfacedby.com/api/v1/console/credits/checkout" \
  -H "X-API-Key: string" \
  -H "Content-Type: application/json" \
  -d '{}'

null

curl -X POST "https://api.surfacedby.com/api/v1/console/credits/checkout/recover" \
  -H "X-API-Key: string" \
  -H "Content-Type: application/json" \
  -d '{}'

null

curl -X GET "https://api.surfacedby.com/api/v1/console/credits/checkouts" \
  -H "X-API-Key: string"

null