Balance & billing

Use the user billing endpoints to read your team’s credit balance and buy top-ups with a saved payment method. Both endpoints require authentication with your API key. Invalid keys return 402.

Check credit balance

GET /user/credits/info returns the authenticated team’s credit balance, a per-lot breakdown, active subscription details, and whether usage is allowed. Use this endpoint to power billing widgets, usage dashboards, or pre-flight checks before running large jobs. For API details see Get credit info.

import requests

response = requests.get(
    "https://api.olostep.com/user/credits/info",
    headers={"Authorization": "Bearer <YOUR_API_KEY>"},
)
print(response.json())

const res = await fetch("https://api.olostep.com/user/credits/info", {
  headers: { Authorization: "Bearer <YOUR_API_KEY>" },
})
console.log(await res.json())

curl -s "https://api.olostep.com/user/credits/info" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Response

{
  "credits": 12500,
  "breakdown": [
    {
      "purchase_kind": "Subscription",
      "allocated_units": 10000,
      "remaining_units": 8500,
      "expiry_date": 1735689600
    },
    {
      "purchase_kind": "Top-up",
      "allocated_units": 5000,
      "remaining_units": 4000,
      "expiry_date": 1743465600
    }
  ],
  "active_subscription": {
    "id": "SUB_PRO",
    "display_name": "Pro",
    "credits": 10000,
    "created_at": 1704067200
  },
  "allow_usage": true
}

Field	Description
`credits`	Total remaining credits across all non-expired lots
`breakdown`	Per-lot detail: type, allocated and remaining units, expiry
`active_subscription`	Current plan (falls back to `SUB_BASE` if none is active)
`allow_usage`	Whether the team can still consume credits

Each lot in breakdown has a purchase_kind of Subscription, Top-up, Manual, Setup, or Pending.

Purchase a top-up

POST /user/purchase-topup charges a saved card on Stripe and buys credits in one step. There is no Checkout redirect or embedded payment UI. Pass the credit amount in the request body:

{ "credits": 10000 }

Field	Description
`credits`	Number of credits to purchase

Supported values: 10,000, 20,000, 80,000, and 100,000. For API details see Purchase top-up.

import requests

response = requests.post(
    "https://api.olostep.com/user/purchase-topup",
    headers={
        "Authorization": "Bearer <YOUR_API_KEY>",
        "Content-Type": "application/json",
    },
    json={"credits": 10000},
)
print(response.status_code)
print(response.json())

const res = await fetch("https://api.olostep.com/user/purchase-topup", {
  method: "POST",
  headers: {
    Authorization: "Bearer <YOUR_API_KEY>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ credits: 10000 }),
})
console.log(res.status)
console.log(await res.json())

curl -s -X POST "https://api.olostep.com/user/purchase-topup" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"credits": 10000}'

Requirements

The team must have a Stripe customer with at least one saved card.
Only one purchase attempt is allowed every 60 seconds per team. If you hit the cooldown, the response is 429 with a Retry-After header.

Responses

200 — payment succeeded:

{
  "success": true,
  "payment_intent_id": "pi_xxx",
  "credits": 10000
}

202 — payment is still processing. Credits are added once Stripe confirms the payment:

{
  "success": true,
  "status": "processing",
  "payment_intent_id": "pi_xxx",
  "message": "Payment is processing. Credits will be added once the payment is confirmed.",
  "credits": 10000
}

Credits are issued by the Stripe webhook after payment confirmation, not directly from the HTTP response. Treat 200 as payment success; poll GET /user/credits/info if you need to confirm the updated balance.

Common errors

Status	Error	When
400	`missing_topup_selector`	`credits` was not sent
400	`invalid_credits`	Credit amount is not in the allowed list
400	`no_stripe_customer`	Team has no Stripe customer
400	`no_payment_method`	No saved card on file
402	`payment_failed`	No saved card completed the charge
429	`purchase_topup_cooldown`	Another purchase was attempted within 60 seconds
503	`payment_status_unknown`	Ambiguous Stripe error; wait before retrying

Automatic refills

To keep your balance from running out, check it on a schedule and buy a top-up when it drops below a threshold. This uses the two endpoints above and works anywhere you can run a script: a cron job, a CI step, a serverless function, or an AI agent before a large job.

Call GET /user/credits/info and read credits.
If credits is below your threshold, call POST /user/purchase-topup with one of the supported amounts.
On 200 or 202, stop. Credits arrive once Stripe confirms the payment, so don’t buy again on the next check until the balance has updated.

import os
import requests

API = "https://api.olostep.com"
HEADERS = {"Authorization": f"Bearer {os.environ['OLOSTEP_API_KEY']}"}
THRESHOLD = 2000      # refill when balance drops below this
TOPUP_CREDITS = 10000  # 10000, 20000, 80000, or 100000

credits = requests.get(f"{API}/user/credits/info", headers=HEADERS).json()["credits"]

if credits < THRESHOLD:
    res = requests.post(
        f"{API}/user/purchase-topup",
        headers=HEADERS,
        json={"credits": TOPUP_CREDITS},
    )
    print(res.status_code, res.json())
else:
    print(f"Balance OK: {credits} credits")

const API = "https://api.olostep.com"
const headers = {
  Authorization: `Bearer ${process.env.OLOSTEP_API_KEY}`,
  "Content-Type": "application/json",
}
const THRESHOLD = 2000 // refill when balance drops below this
const TOPUP_CREDITS = 10000 // 10000, 20000, 80000, or 100000

const { credits } = await (await fetch(`${API}/user/credits/info`, { headers })).json()

if (credits < THRESHOLD) {
  const res = await fetch(`${API}/user/purchase-topup`, {
    method: "POST",
    headers,
    body: JSON.stringify({ credits: TOPUP_CREDITS }),
  })
  console.log(res.status, await res.json())
} else {
  console.log(`Balance OK: ${credits} credits`)
}

#!/usr/bin/env bash
# Requires jq. Refill when balance drops below THRESHOLD.
THRESHOLD=2000
TOPUP_CREDITS=10000

credits=$(curl -s "https://api.olostep.com/user/credits/info" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" | jq '.credits')

if [ "$credits" -lt "$THRESHOLD" ]; then
  curl -s -X POST "https://api.olostep.com/user/purchase-topup" \
    -H "Authorization: Bearer $OLOSTEP_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"credits\": $TOPUP_CREDITS}"
else
  echo "Balance OK: $credits credits"
fi

To run the check every hour with cron:

0 * * * * OLOSTEP_API_KEY=your_key /usr/bin/python3 /path/to/refill.py

Pick a threshold that covers your usage between checks. If you run the check hourly and use about 1,000 credits an hour, a threshold of 2,000 leaves a buffer while a top-up is processing.

Each run can charge your saved card. Run only one refill job per team, and handle 429 (purchase_topup_cooldown) and 503 (payment_status_unknown) by waiting for the next scheduled check instead of retrying right away. A 402 (payment_failed) means your card was declined; update it in the dashboard before the next run.

Get Started

Features

Balance & billing

Check credit balance

Response

Purchase a top-up

Requirements

Responses

Common errors

Automatic refills

​Check credit balance

​Response

​Purchase a top-up

​Requirements

​Responses

​Common errors

​Automatic refills

Check credit balance

Response

Purchase a top-up

Requirements

Responses

Common errors

Automatic refills