ToAPIsToAPIs
Billing

List top-up orders

Page through the main account's own top-up orders

GET
/api/v1/billing/topups

Note for users in mainland China: Please use https://api.toapis.cn as the API endpoint (Base URL). Replace https://api.toapis.com with https://api.toapis.cn in the examples in this document.

See Access for authentication, pagination, and errors.

Behavior

Returns the account's top-up orders, for reconciling payments and credited amounts. Only the main account can query its own billing; sub-accounts get HTTP 403, and a main account cannot use this endpoint to query member bills.

Returns top-up orders by creation time and order ID descending, defaulting to the last 31 days with a 366-day maximum. recorded_payment_amount and payment_currency record the original payment amount and currency and are not used to derive credits.

planned_credits is the intended credit amount, credited_credits the confirmed amount, and refunded_credits records refunds separately without subtracting from the original credit. Non-successful orders have credited_credits="0".

Historically unconfirmable amounts are null, with reasons in meta. Only TopUp orders are included, excluding manually granted credits and standalone offline refunds.

refund=null does not guarantee no other refund exists, and a local refund snapshot does not mean the card was actually credited. This endpoint does not query the payment platform or reconcile orders.

Authentication

Authorizationstringheaderrequired

Use Bearer YOUR_SYSTEM_ACCESS_TOKEN. Model API keys are not accepted. X-User-Id is not required.

Request parameters

fromstringquery

Inclusive start in RFC 3339 with a timezone. Provide together with to.

Constraints: date-time.

tostringquery

Exclusive end in RFC 3339 with a timezone. Must be later than from.

Constraints: date-time.

cursorstringquery

Pass the previous next_cursor unchanged and keep the same filters. Restart when filters change.

Constraints: maxLength=2048.

limitintegerquerydefault: 20

Maximum number of items per page.

Constraints: minimum=1; maximum=100; Default: 20.

providerstringquery

Payment provider.

Constraints: stripe, wechat, alipay, creem, nowpayments, offline.

statusstringquery

Top-up order status: pending, success, superseded, expired, failed, partially_paid.

Constraints: pending, success, superseded, expired, failed, partially_paid.

Request examples

requestExample

curl --request GET \
  --url 'https://api.toapis.com/api/v1/billing/topups?from=2026-11-01T00:00:00Z&to=2026-11-02T00:00:00Z&provider=stripe&limit=20' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'
import requests

response = requests.get(
    "https://api.toapis.com/api/v1/billing/topups",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    params={
        "from": "2026-11-01T00:00:00Z",
        "to": "2026-11-02T00:00:00Z",
        "provider": "stripe",
        "limit": "20"
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())
const url = new URL("https://api.toapis.com/api/v1/billing/topups");
url.search = new URLSearchParams({
  "from": "2026-11-01T00:00:00Z",
  "to": "2026-11-02T00:00:00Z",
  "provider": "stripe",
  "limit": "20"
}).toString();

const response = await fetch(url, {
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN" },
  signal: AbortSignal.timeout(30_000),
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

Response fields

Examples use fictional data and assume credits_per_usd="100". Use the conversion rate returned by the API.

Results are in data.items. Paginate with has_more and next_cursor; the final cursor is null. No total count is returned.

codeinteger

Numeric result code; 0 means success.

messagestring

Response message; empty on success. Error messages are localized.

dataobject

Result object for this query.

data.itemsobject[]

Records on this page; [] when empty.

data.items[].idstring

Internal top-up order ID. Use trade_no for the detail endpoint. Returned as a decimal ID string.

data.items[].trade_nostring

Platform top-up order number used for details, not an external payment order ID.

data.items[].providerstring

Payment service provider.

data.items[].statusstring

Top-up order status. Only successful orders represent confirmed crediting.

data.items[].trigger_typestring | null

Top-up trigger, such as manual or automatic. Historical values can be null.

data.items[].created_atstring | null

Creation time. RFC 3339 timestamp with a timezone. null when unknown or inapplicable.

data.items[].completed_atstring | null

Order completion time. RFC 3339 timestamp with a timezone. null when unknown or inapplicable.

data.items[].recorded_payment_amountstring | null

Original-currency payment amount recorded locally. See payment_currency; do not infer credits from it. Returned as a decimal string to preserve precision. null when unknown or inapplicable.

data.items[].payment_currencystring | null

Original payment currency recorded on the order. null when unknown or inapplicable.

data.items[].planned_creditsstring | null

Planned credits, not the confirmed credited amount. Returned as a decimal string to preserve precision. null when unknown or inapplicable.

data.items[].credited_creditsstring | null

Confirmed credited amount. Non-successful orders use "0"; unverifiable historical amounts are null. Returned as a decimal string to preserve precision.

data.items[].refunded_creditsstring | null

Refunded credits recorded on the order, shown separately without reducing the original credited amount. Returned as a decimal string to preserve precision. null when unknown or inapplicable.

data.items[].refundobject | null

Local order refund snapshot. null does not rule out standalone offline refunds or prove card receipt.

data.items[].refund.statusstring

Refund state recorded on the order.

data.items[].refund.recorded_amountstring | null

Original-currency refund amount recorded locally; currency is in currency. Returned as a decimal string to preserve precision. null when unknown or inapplicable.

data.items[].refund.currencystring | null

Original currency used by the amounts. null when unknown or inapplicable.

data.items[].refund.recorded_atstring | null

Time recorded for the local refund. RFC 3339 timestamp with a timezone. null when unknown or inapplicable.

data.items[].metaobject

Metadata describing the source, query scope, and accounting basis.

data.items[].meta.sourcestring

Data source. Local configuration or ledger snapshots do not imply live Stripe state. Fixed value: "local_ledger".

data.items[].meta.refund_coveragestring

Refund coverage, limited to the order refund snapshot. Fixed value: "order_snapshot_only".

data.items[].meta.standalone_offline_refunds_includedboolean

Whether standalone offline refunds are included. Currently false.

data.items[].meta.payment_amount_basisstring

Basis for payment amounts: the local order snapshot. Fixed value: "local_order_snapshot".

data.items[].meta.consistencystring

Consistency model. eventual means records can be updated later.

data.items[].meta.payment_amount_sourcestring

Record source used to confirm the payment amount.

data.items[].meta.credit_amount_sourcestring

Record source used to confirm credited funds.

data.has_moreboolean

Whether another page is available.

data.next_cursorstring | null

Pass this cursor unchanged with the same filters. It is null on the last page.

data.metaobject

Metadata describing the source, query scope, and accounting basis.

data.meta.sourcestring

Data source. Local configuration or ledger snapshots do not imply live Stripe state.

data.meta.scopestring

Ownership scope of the query: the authenticated account itself.

data.meta.fromstring

Inclusive start of the query time range.

data.meta.tostring

Exclusive end of the query time range.

data.meta.consistencystring

Consistency model. eventual means records can be updated later.

data.meta.refund_coveragestring

Refund coverage, limited to the order refund snapshot.

data.meta.standalone_offline_refunds_includedboolean

Whether standalone offline refunds are included. Currently false.

Response examples

responseExample

{
  "code": 0,
  "message": "",
  "data": {
    "items": [
      {
        "id": "501",
        "trade_no": "trade_example_01",
        "provider": "stripe",
        "status": "success",
        "trigger_type": "manual",
        "created_at": "2026-11-01T08:00:00Z",
        "completed_at": "2026-11-01T08:01:00Z",
        "recorded_payment_amount": "10",
        "payment_currency": "USD",
        "planned_credits": "1000",
        "credited_credits": "1000",
        "refunded_credits": "0",
        "refund": null,
        "meta": {
          "source": "local_ledger",
          "consistency": "eventual",
          "payment_amount_basis": "local_order_snapshot",
          "refund_coverage": "order_snapshot_only",
          "standalone_offline_refunds_included": false,
          "payment_amount_source": "paid_amount",
          "credit_amount_source": "credited_credits"
        }
      }
    ],
    "has_more": false,
    "next_cursor": null,
    "meta": {
      "source": "local_ledger",
      "scope": "self",
      "from": "2026-11-01T00:00:00Z",
      "to": "2026-11-02T00:00:00Z",
      "consistency": "eventual",
      "refund_coverage": "order_snapshot_only",
      "standalone_offline_refunds_included": false
    }
  }
}