ToAPIsToAPIs
Billing

Get top-up order

Read a top-up order by trade number

GET
/api/v1/billing/topups/{trade_no}

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 details of a single top-up order by trade_no. 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.

Looks up one of your orders by trade_no. External payment-platform order numbers are not accepted. Orders owned by others, missing orders, and standalone offline refunds return 404. This endpoint does not query the payment platform or reconcile orders.

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".

refund=null does not guarantee no other refund exists, and a local refund snapshot does not mean the card was actually credited.

Authentication

Authorizationstringheaderrequired

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

Request parameters

trade_nostringpathrequired

Platform top-up order number, not an external payment-provider order ID.

Constraints: minLength=1; maxLength=255.

Request examples

requestExample

curl --request GET \
  --url 'https://api.toapis.com/api/v1/billing/topups/trade_example_01' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'
import requests

response = requests.get(
    "https://api.toapis.com/api/v1/billing/topups/trade_example_01",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    timeout=30,
)
response.raise_for_status()
print(response.json())
const url = new URL("https://api.toapis.com/api/v1/billing/topups/trade_example_01");

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.

codeinteger

Numeric result code; 0 means success.

messagestring

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

dataobject

Result object for this query.

data.idstring

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

data.trade_nostring

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

data.providerstring

Payment service provider.

data.statusstring

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

data.trigger_typestring | null

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

data.created_atstring | null

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

data.completed_atstring | null

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

data.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.payment_currencystring | null

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

data.planned_creditsstring | null

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

data.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.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.refundobject | null

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

data.refund.statusstring

Refund state recorded on the order.

data.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.refund.currencystring | null

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

data.refund.recorded_atstring | null

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

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. Fixed value: "local_ledger".

data.meta.refund_coveragestring

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

data.meta.standalone_offline_refunds_includedboolean

Whether standalone offline refunds are included. Currently false.

data.meta.payment_amount_basisstring

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

data.meta.consistencystring

Consistency model. eventual means records can be updated later.

data.meta.payment_amount_sourcestring

Record source used to confirm the payment amount.

data.meta.credit_amount_sourcestring

Record source used to confirm credited funds.

Response examples

responseExample

{
  "code": 0,
  "message": "",
  "data": {
    "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"
    }
  }
}