List top-up orders | ToAPIs Documentation

GET

/api/v1/account/billing/topups

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

See Getting started for authentication, pagination, and errors.

Behavior

Only a main account can read its own billing. Subaccounts receive HTTP 403. A main account cannot read member billing through this endpoint.

Defaults to 31 days, allows up to 366 days, and sorts by creation time and order ID descending. recorded_payment_amount/payment_currency preserve the original payment currency and do not determine credits. planned_credits is planned, credited_credits is confirmed, and refunded_credits is recorded separately without reducing original credited amounts. Non-successful orders have credited_credits="0"; unverifiable historical amounts are null with reasons in meta. Only TopUp orders are included, not manual gifts or standalone offline refunds. refund=null does not rule out other refunds. A local refund snapshot does not prove card receipt. GET does not query or repair payment-provider orders.

Authentication

Authorizationstringheaderrequired

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

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

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

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

requestExample

curl --request GET \
  --url 'https://toapis.com/api/v1/account/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://toapis.com/api/v1/account/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://toapis.com/api/v1/account/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.

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
    }
  }
}