Billing API - ACN Documentation

All billing endpoints require Cognito authentication (i.e., your dashboard session token, not an API key). Use these from your server-side code or dashboard integrations. Base URL: https://api.acn.exchange

Balance

Get Balance

Returns your current credit balance, daily spend, and any active spending limits.

GET /v1/billing/balance
Authorization: Bearer <cognito_token>

Response

{
  "balanceCredits": "8500000",
  "balanceUsdc": "8.500000",
  "dailySpentCredits": "250000",
  "dailySpentUsdc": "0.250000",
  "dailySpendLimitCredits": null,
  "perCallLimitCredits": null,
  "lowBalanceAlertThreshold": "1000000",
  "status": "active"
}

Field	Description
`balanceCredits`	Available credits (1 credit = $0.000001)
`balanceUsdc`	Same balance expressed in USDC
`dailySpentCredits`	Credits consumed today (UTC)
`dailySpendLimitCredits`	Your daily cap (`null` = no limit)
`perCallLimitCredits`	Max credits per call (`null` = no limit)
`status`	`active`, `suspended`, or `closed`

API keys can also call GET /v1/billing/balance to check the credit balance of the account they belong to.

Stripe Top-Ups

Create Checkout Session

Initiates a Stripe Checkout session for a credit top-up.

POST /v1/billing/checkout
Authorization: Bearer <cognito_token>
Content-Type: application/json

Request Body

{
  "amountUsdCents": 1000,
  "successUrl": "https://yourapp.com/billing?status=success",
  "cancelUrl": "https://yourapp.com/billing?status=cancelled"
}

Field	Type	Required	Description
`amountUsdCents`	integer	Yes	Amount in USD cents. Minimum: `500` ( $5.00), Maximum: `1000000` ($ 10,000)
`successUrl`	string	Yes	URL to redirect to after successful payment
`cancelUrl`	string	Yes	URL to redirect to if the user cancels

Response

{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_live_...",
  "sessionId": "cs_live_...",
  "creditsToReceive": "10000000"
}

Redirect the user to checkoutUrl. The session expires in 30 minutes.

List Payments

Returns your Stripe payment history.

GET /v1/billing/payments?page=1&limit=20
Authorization: Bearer <cognito_token>

Response

{
  "payments": [
    {
      "id": "pay_abc123",
      "amountUsd": "10.00",
      "creditsGranted": "10000000",
      "status": "completed",
      "receiptUrl": "https://receipt.stripe.com/...",
      "createdAt": "2026-03-19T10:00:00Z",
      "completedAt": "2026-03-19T10:00:04Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5
  }
}

Payment statuses: pending · completed · failed · expired · refunded

Transactions

List Transactions

Full ledger of every credit movement on your account — deposits, debits, refunds, admin credits, and coupons.

GET /v1/billing/transactions?page=1&limit=20&type=debit
Authorization: Bearer <cognito_token>

Query Parameters

Param	Description
`page`	Page number (default: 1)
`limit`	Results per page (default: 20, max: 100)
`type`	Filter by type: `deposit`, `debit`, `refund`, `admin_credit`, `coupon_credit`
`from`	ISO date — only return transactions after this date
`to`	ISO date — only return transactions before this date

Response

{
  "transactions": [
    {
      "id": "txn_abc123",
      "type": "deposit",
      "amountCredits": "10000000",
      "amountUsdc": "10.000000",
      "balanceAfter": "10000000",
      "description": "Credit top-up: $10.00",
      "referenceType": "stripe_payment",
      "referenceId": "pi_3abc...",
      "createdAt": "2026-03-19T10:00:00Z"
    },
    {
      "id": "txn_abc124",
      "type": "debit",
      "amountCredits": "-2000",
      "amountUsdc": "-0.002000",
      "balanceAfter": "9998000",
      "description": "API call: text-summarizer",
      "providerId": "prv_xyz",
      "capabilityId": "cap_abc",
      "createdAt": "2026-03-19T10:05:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 42 }
}

Usage

Get Usage Breakdown

Daily usage aggregated by provider and capability, for dashboard charts and analytics.

GET /v1/billing/usage?from=2026-03-01&to=2026-03-19
Authorization: Bearer <cognito_token>

Query Parameters

Param	Description
`from`	Start date (`YYYY-MM-DD`)
`to`	End date (`YYYY-MM-DD`)
`groupBy`	`day` (default) or `provider`

Response

{
  "summary": {
    "totalCreditsSpent": "5250000",
    "totalUsdcSpent": "5.250000",
    "totalCalls": 312,
    "dateRange": { "from": "2026-03-01", "to": "2026-03-19" }
  },
  "daily": [
    {
      "date": "2026-03-19",
      "creditsSpent": "250000",
      "usdcSpent": "0.250000",
      "callCount": 18,
      "providerBreakdown": [
        { "providerId": "prv_xyz", "providerName": "text-summarizer", "creditsSpent": "200000", "callCount": 10 }
      ]
    }
  ]
}

Export Usage as CSV

GET /v1/billing/usage/export?from=2026-03-01&to=2026-03-19
Authorization: Bearer <cognito_token>

Returns a text/csv response with one row per call, including timestamps, provider, capability, credits charged, and outcome.

Spending Limits

Update Spending Limits

PUT /v1/billing/limits
Authorization: Bearer <cognito_token>
Content-Type: application/json

Request Body

{
  "dailySpendLimitUsdc": "50.00",
  "perCallLimitUsdc": "0.50"
}

Field	Type	Description
`dailySpendLimitUsdc`	string \| null	Daily cap in USDC. `null` removes the limit.
`perCallLimitUsdc`	string \| null	Per-call cap in USDC. `null` removes the limit.

Response

{
  "dailySpendLimitCredits": "50000000",
  "dailySpendLimitUsdc": "50.000000",
  "perCallLimitCredits": "500000",
  "perCallLimitUsdc": "0.500000"
}

When a limit is exceeded, calls return HTTP 402 with code ACN-CREDIT-002.

Notifications

Update Alert Preferences

PUT /v1/billing/alerts
Authorization: Bearer <cognito_token>
Content-Type: application/json

Request Body

{
  "lowBalanceThresholdUsdc": "5.00",
  "emailNotifications": {
    "lowBalance": true,
    "dailyLimitReached": true,
    "paymentConfirmed": true,
    "unusualActivity": true,
    "dailySummary": false,
    "weeklySummary": true
  }
}

Response: 200 OK with the updated preferences.

Coupons

Redeem a Coupon

POST /v1/billing/coupons/redeem
Authorization: Bearer <cognito_token>
Content-Type: application/json

Request Body

{
  "code": "LAUNCH50"
}

Response

{
  "code": "LAUNCH50",
  "creditsGranted": "50000000",
  "usdcEquivalent": "50.000000",
  "description": "Launch promotion: $50 free credits",
  "newBalance": "55000000"
}

Error responses:

404 — Coupon code not found
409 — Coupon already redeemed
410 — Coupon expired

Error Codes

Code	HTTP Status	Description
`ACN-CREDIT-001`	402	Insufficient credits to cover the call
`ACN-CREDIT-002`	402	Spending limit (daily or per-call) would be exceeded
`ACN-BILLING-001`	400	Amount below minimum ($5.00)
`ACN-BILLING-002`	400	Amount above maximum ($10,000)
`ACN-COUPON-001`	404	Coupon code not found
`ACN-COUPON-002`	409	Coupon already redeemed by this account
`ACN-COUPON-003`	410	Coupon has expired

API Reference

​Balance

​Get Balance

​Stripe Top-Ups

​Create Checkout Session

​List Payments

​Transactions

​List Transactions

​Usage

​Get Usage Breakdown

​Export Usage as CSV

​Spending Limits

​Update Spending Limits

​Notifications

​Update Alert Preferences

​Coupons

​Redeem a Coupon

​Error Codes

Balance

Get Balance

Stripe Top-Ups

Create Checkout Session

List Payments

Transactions

List Transactions

Usage

Get Usage Breakdown

Export Usage as CSV

Spending Limits

Update Spending Limits

Notifications

Update Alert Preferences

Coupons

Redeem a Coupon

Error Codes