API reference

Wallet

Balance, transactions, top-ups, auto top-up and referrals on one prepaid wallet.

One prepaid wallet per organization, in USD, accounted in integer microdollars on an immutable ledger. Every reserve, settle, release, top-up, bonus, refund, chargeback and reversal is a ledger entry you can read back.

Balance

GET /v1/wallet

{"currency": "USD", "balance": "24.35", "reserved": "0.10", "available": "24.25"}

reserved is held by in-flight runs; available is what new runs can reserve against.

Transactions

GET /v1/wallet/transactions

Newest first, limit default 50, max 200:

{
  "items": [
    {
      "id": "txn_...",
      "type": "usage_charge",
      "amount": "-0.05",
      "balance_after": "24.30",
      "reference": "run_...",
      "note": null,
      "created_at": "2026-09-02T09:30:01+00:00"
    }
  ]
}

type is one of:

Type	Entry
`reservation`	a run's hold, taken from the balance before it executes
`usage_charge`	what a run was charged when it settled; an Apify run can get a second one minutes later, when Apify's final bill for it arrives (positive when part of the charge is returned)
`reservation_release`	the part of a hold a run did not use, or all of it when the run is not billed
`topup`	a deposit (Stripe checkout or auto top-up)
`promotional_credit`	signup or promotional credit
`referral_credit`	a referral bonus, or its reversal (`reference` starts with `reversal:`)
`referral_commission`	your share of a referred workspace's calls, or its reversal
`subscription_charge`	the 30-day charge for a connected account
`plan_credit`	a paid monthly plan fee, added as credit for the month it pays for
`plan_credit_expiry`	what was left of a month's plan credit when the month ended (zero when it was all used)
`plan_credit_reversal`	plan credit taken back because the plan payment was refunded or disputed
`refund`	a refunded deposit taken back out of the wallet
`chargeback`	a disputed deposit taken back out of the wallet (credited again if the dispute is won)
`manual_adjustment`	a correction made by RouterGrowth support, with a `note`

Top up

POST /v1/wallet/topups/checkout

{"amount": "20"}

Minimum self-service top-up is $10.00. In production this returns a Stripe Checkout URL:

{"status": "checkout", "checkout_url": "https://checkout.stripe.com/...", "session_id": "cs_..."}

The wallet is credited by the verified Stripe webhook once payment succeeds, never by this endpoint's response. In the sandbox (test keys, no Stripe), the same call credits a clearly-labeled simulated top-up so the full flow is testable.

Auto top-up

GET  /v1/wallet/auto-topup
POST /v1/wallet/auto-topup

{"enabled": true, "threshold": "10", "amount": "20"}

When the balance drops below threshold, the card of your latest checkout top-up is charged amount. Requires Stripe (a completed checkout with a saved payment method). When a refill fails, last_error in the GET response names the card and the bank's reason, and the refill pauses for 24 hours instead of retrying the same card; a checkout top-up with a card that works switches refills to that card and re-arms them. Changing the setting needs a dashboard session: an API key can read it, not switch it on, so a leaked key cannot turn the saved card into a standing charge.

Invoices

GET /v1/wallet/invoices
GET /v1/wallet/invoices/{id}

Every card payment gets an invoice: one per checkout top-up, per auto top-up refill and per monthly plan payment, with tax where it applies. The list is newest first, up to the 100 most recent:

{
  "items": [
    {
      "id": "in_...",
      "number": "ABCD1234-0007",
      "kind": "topup",
      "description": "Wallet top-up",
      "status": "paid",
      "total": "20.00",
      "currency": "USD",
      "created_at": "2026-10-12T09:30:01+00:00",
      "paid_at": "2026-10-12T09:30:04+00:00",
      "pay_url": null
    }
  ],
  "has_more": false
}

kind is topup, auto_topup, plan or other. total is what was charged, tax included, so it can be higher than the credit the wallet received. status is paid, or open for an invoice that is issued and still due (a plan renewal whose card was declined); pay_url is then the page to pay it on, and null otherwise.

One invoice in full adds what the document shows: issued_at, due_at, the issuer (seller), your billing details (bill_to: name, email, address lines, country code, tax IDs), the lines (description, quantity, unit amount, amount, and the period a plan line covers), subtotal, taxes, amount_paid and amount_due. The dashboard's Wallet page draws the invoice from it: open one there to print it or save it as a PDF. "Edit billing details" on the same page changes the name, address and tax ID the next invoices show.

USDC top-ups are not card payments and have no invoice: their record is the topup entry in the transactions above. Reading invoices needs a dashboard session, like changing auto top-up: they carry your billing name, address and tax ID.

Referrals

GET /v1/referrals

Your referral code and link, the program terms, and what your referrals have earned you. The code is minted on first call. The referred workspace gets a bonus on its first qualifying deposit; you earn a share of net revenue on their runs for a limited period (current terms). Self-referrals, refunds and disputes can reverse both: the rules are in the terms.

Previous
Tables Next
API keys

Reading this as an agent? This page as markdown: /docs/api/wallet.md · every page: /docs/llms.txt