Skip to content
Docs

Credits & billing

The prepaid credit wallet — available vs held credits, bonus tiers, top-ups, auto-recharge, what happens without enough credits, and refunds.

Orders are paid from a prepaid credit wallet: you buy credits, and each order spends credits. There are no invoices to chase and no card charge per order — your integration only needs to keep the wallet funded. One credit cent = one US cent.

The wallet

cURL
curl https://swaglists.com/api/v1/wallet -H "Authorization: Bearer $API_KEY"
Response
{
  "object": "wallet",
  "mode": "live",
  "livemode": true,
  "currency": "usd",
  "available": 482550,
  "held": 12480,
  "total": 495030,
  "low_balance_threshold": 10000
}
Field Meaning
available Spendable credits, in cents. New orders reserve from here. Can be negative after a payment dispute.
held Credits reserved for confirmed orders that have not been accepted for production yet.
total available + held.
low_balance_threshold You get a wallet.low_balance event (and an email) when available drops below it. Set it in Settings → Orders.

Live and test mode have separate wallets. Test credits are free — see Test mode.

How an order uses credits

  1. Confirm — the order total is moved from available to held (a hold transaction).
  2. Accepted for production — the held credits are spent (capture). An order produced in several parts captures each part separately.
  3. Canceled or failed before that — the held credits go back to available (release). Canceled after capture? The spent credits are refunded (refund).

Every change is an immutable transaction — list them with GET /wallet/transactions (filter by type or order_id):

Transaction type Meaning
topup Credits you bought (the paid amount).
bonus Bonus credits of a top-up (a separate entry).
hold Credits reserved for an order (amount −X, held_delta +X).
release Reserved credits returned to available (canceled/failed order).
capture Reserved credits spent when production of (part of) an order was accepted (held_delta −X).
charge Credits spent directly, without a reservation.
refund Credits refunded for an order.
adjustment A correction by support (positive or negative), with a reason.
reversal Credits taken back after a top-up was refunded or disputed (can make available negative).
test_credit Free test credits (test mode only).

Bonus tiers

Bigger top-ups earn bonus credits on top of what you pay:

You pay Bonus Example: credits you receive
Less than $1,000 0% $500 → $500
$1,000 – $2,499.99 3% $1,000 → $1,030
$2,500 – $4,999.99 4% $2,500 → $2,600
$5,000 and above 5% $5,000 → $5,250

For example, paying $5,000 gives $5,250 in credits. The bonus is added as a separate bonus transaction. Tiers can change; the Buy credits page always shows the current ones before you pay. Bonus credits are not refundable.

Buying credits (top-ups)

Top-ups are made in the dashboard (Wallet → Buy credits) by owners, admins and finance members. Pay by card or US bank account (ACH); bank transfer may also be available. The minimum top-up is $100.

  • Card — credits arrive within seconds.
  • US bank account (ACH) — cheaper for large amounts; credits arrive when the payment clears (usually a few business days). The top-up is processing meanwhile.

You receive topup.succeeded and wallet.credited events when credits arrive (topup.failed if a payment fails). List top-ups with GET /topups.

Invoices. Every card or bank purchase comes with an invoice (download it from the purchase in the wallet). It shows the legal name, billing address and tax ID (VAT, EIN, GST…) from Settings → Billing — fill them in before buying. Reselling? Upload your resale or exemption certificate on the same page; once our team approves it, no sales tax is added to your orders.

Auto-recharge

Turn on Wallet → Recharge automatically: when available falls below your threshold, we charge your saved card or bank account for the amount you chose (bonus tiers apply). Failed recharges notify you and auto-recharge pauses after repeated failures. With auto-recharge on, orders rarely wait for credits.

When credits run out

What happens to an order your available credits cannot cover is a setting (Settings → Orders → When credits run out):

Setting Result
Hold (default) The order is created on_hold with hold_reason: insufficient_funds and funds_status: awaiting. You get order.on_hold. As soon as credits arrive (top-up, auto-recharge, refund), held orders continue automatically, oldest first, and you get order.processing.
Hold, release manually (hold_manual) The order is created on_hold / insufficient_funds like Hold, but adding credits does not release it. You release held orders yourself: one at a time or in bulk from Orders in the dashboard, or with POST /orders/{id}/confirm from the API. Releasing reserves the order total first; if your credits still don't cover it, it stays on hold (the API answers 402 insufficient_funds). New orders your credits cover are not blocked by held ones.
Reject POST /orders (and POST /orders/{id}/confirm) fail with 402 insufficient_funds; nothing is created. The error includes required_amount and available_amount.

Whatever the setting, nothing is ever sent to production unless its credits are reserved in your wallet first. With Hold you can also release a held order early (after a top-up, before the automatic retry runs) the same way: dashboard Release or POST /orders/{id}/confirm.

Holding is friendlier when your customer has already paid you; rejecting suits integrations that want to retry themselves. When you retry a rejected request after adding credits, send it with a new Idempotency-Key (for example order-1042:2): the 402 is stored under the original key for 24 hours, so reusing that key returns the same error. external_id still prevents a duplicate order. Check GET /account → settings.insufficient_funds_behavior to see which applies.

POST /orders/estimate returns wallet_available and sufficient_funds so you can check before ordering.

Refunds

  • Order refunds go to your wallet. Canceling an order releases or refunds its credits automatically. If support refunds an order (for example a damaged item), the credits are added to available (refund transaction, order.refunded and wallet.credited events).
  • Unused credits can be refunded to the original payment method on request — use Settings → Billing → Refund unused credits (or contact support). Only the paid portion of unused credits is refundable; bonus credits from that top-up are removed proportionally. Owners can also ask to close the account there.
  • Payment disputes (chargebacks) on a top-up remove its credits, which can make available negative; new orders wait until the balance is positive again.

Credits API

Request Returns
GET /wallet The wallet of the key's mode.
GET /wallet/transactions Every balance change, newest first (type, order_id filters).
GET /topups, GET /topups/{id} Credit purchases (live mode).
POST /test/wallet/fund Free test credits (test mode).

All need the wallet:read scope (the test helper needs full access).