Wallet

Your wallet holds the money we charge for shipping, handling, purchase orders and shipments. Amounts are in US cents. The API reads the wallet; top up and pay in the portal. See Charges and your wallet for when money is held or charged.

Your available balance is balanceCents + creditLimitCents - heldForShippingCents. An order without problems holds its estimated shipping and handling fee (heldForShippingCents) once its stock is fully reserved; a BACKORDERED order holds nothing yet. The hold is released when the order is weighed and charged, cancelled or returned, or when an unpaid hold expires. If the balance is short when the order is weighed, the hold stays.

Get the wallet balance

GET /v1/wallet

Property	Value
URL	`https://api.rephut.com/v1/wallet`
Permission	`wallet:read`
Access	Read: counts towards the read limit and works while your account is on hold
Idempotency-Key	Not used
Success	200 OK

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer <your API key>`. See Authentication.

Response

200 with data, an object with the fields below.

Field	Type	Description
`currency`	string	Currency of every amount in this object. Always `USD`.
`balanceCents`	integer	Your wallet balance in US cents. It can be negative when you use your credit limit.
`creditLimitCents`	integer	Credit we allow on top of your balance, in US cents.
`heldForShippingCents`	integer	Set aside for orders waiting to be packed.
`availableCents`	integer	balanceCents + creditLimitCents - heldForShippingCents.

Errors

Code	HTTP status	Meaning
`invalid_api_key`	401	The API key is missing, malformed, revoked or no longer valid.
`account_action_required`	403	Sign in to the portal and finish the required account steps first.
`api_not_enabled`	403	API access is not enabled for this account.
`insufficient_scope`	403	The API key does not have the permission this call needs.
`validation_failed`	422	The input is not valid. `details` lists each field and the reason.
`rate_limited`	429	Too many requests. Wait for the number of seconds in Retry-After.
`internal_error`	500	Unexpected error. Quote X-Request-Id when you contact support.

Handle errors by code. See Errors.

curlNode.jsPython

curl 'https://api.rephut.com/v1/wallet' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY"

const response = await fetch("https://api.rephut.com/v1/wallet", {
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);

import os

import requests

response = requests.get(
    "https://api.rephut.com/v1/wallet",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.json())

Response 200

{
  "success": true,
  "data": {
    "currency": "USD",
    "balanceCents": 125000,
    "creditLimitCents": 50000,
    "heldForShippingCents": 1840,
    "availableCents": 173160
  }
}

List wallet transactions

GET /v1/wallet/ledger

Every top-up, payment, charge and refund that changed the balance. Newest first.

Property	Value
URL	`https://api.rephut.com/v1/wallet/ledger`
Permission	`wallet:read`
Access	Read: counts towards the read limit and works while your account is on hold
Idempotency-Key	Not used
Success	200 OK

Query parameters

Field	Type	Required	Description
`page`	integer	No	Page number. See Pagination. From 1 to 10,000. Default: `1`.

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer <your API key>`. See Authentication.

Response

200 with data, a list of objects with the fields below (up to one page), and meta with total, page, limit and pageCount. See Pagination.

Field	Type	Description
`id`	string	Transaction id.
`createdAt`	string (date-time)	When the transaction was recorded.
`kind`	string	What kind of transaction this is. See Transaction kinds. One of `RECHARGE`, `RECHARGE_VOID`, `GOODS_DEBIT`, `GOODS_REFUND`, `GOODS_REFUND_VOID`, `SHIPPING_DEBIT`, `SURCHARGE`, `ADJUST`, `HANDLING_DEBIT`, `SHIPPING_REFUND`, `HANDLING_REFUND`, `SHIPMENT_DEBIT`, `SHIPMENT_REFUND`, `SHIPMENT_REFUND_VOID`, `SURCHARGE_VOID`.
`kindLabel`	string	English text for display. It may change; rely on the code next to it.
`reference`	string	Order, purchase order or shipment number, or the payment method of a top-up.
`currency`	string	Currency of the amounts. Always `USD`.
`amountCents`	integer	Change to your balance in US cents: positive adds money, negative takes it away.
`balanceAfterCents`	integer	Your balance right after this transaction, in US cents.
`note`	string	Only adjustments carry a note.

Errors

Code	HTTP status	Meaning
`invalid_api_key`	401	The API key is missing, malformed, revoked or no longer valid.
`account_action_required`	403	Sign in to the portal and finish the required account steps first.
`api_not_enabled`	403	API access is not enabled for this account.
`insufficient_scope`	403	The API key does not have the permission this call needs.
`validation_failed`	422	The input is not valid. `details` lists each field and the reason.
`rate_limited`	429	Too many requests. Wait for the number of seconds in Retry-After.
`internal_error`	500	Unexpected error. Quote X-Request-Id when you contact support.

Handle errors by code. See Errors.

curlNode.jsPython

curl 'https://api.rephut.com/v1/wallet/ledger?page=1' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY"

const response = await fetch("https://api.rephut.com/v1/wallet/ledger?page=1", {
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);

import os

import requests

response = requests.get(
    "https://api.rephut.com/v1/wallet/ledger?page=1",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.json())

Response 200

{
  "success": true,
  "data": [
    {
      "id": "cm3l9e1d0002wlt4a8b7c6d5",
      "createdAt": "2026-11-05T09:12:44.000Z",
      "kind": "SHIPPING_DEBIT",
      "kindLabel": "Shipping",
      "reference": "D2611050007",
      "currency": "USD",
      "amountCents": -1240,
      "balanceAfterCents": 125000,
      "note": ""
    },
    {
      "id": "cm3l9e1d0001wlt4a8b7c6d4",
      "createdAt": "2026-11-03T02:30:00.000Z",
      "kind": "RECHARGE",
      "kindLabel": "Top-up",
      "reference": "Bank transfer",
      "currency": "USD",
      "amountCents": 100000,
      "balanceAfterCents": 126240,
      "note": ""
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 50,
    "pageCount": 1
  }
}

List top-ups

GET /v1/wallet/top-ups

Includes pending, rejected and reversed top-ups. Newest first.

Property	Value
URL	`https://api.rephut.com/v1/wallet/top-ups`
Permission	`wallet:read`
Access	Read: counts towards the read limit and works while your account is on hold
Idempotency-Key	Not used
Success	200 OK

Query parameters

Field	Type	Required	Description
`page`	integer	No	Page number. See Pagination. From 1 to 10,000. Default: `1`.

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer <your API key>`. See Authentication.

Response

200 with data, a list of objects with the fields below (up to one page), and meta with total, page, limit and pageCount. See Pagination.

Field	Type	Description
`id`	string	Top-up id. Webhook `wallet.top_up_approved` carries this id.
`status`	string	Top-up status. See Top-up statuses. One of `PENDING`, `CONFIRMED`, `REJECTED`, `VOIDED`.
`statusLabel`	string	English text for display. It may change; rely on the code next to it.
`paidOn`	string (date)	The day the payment was made, as recorded (YYYY-MM-DD, China time).
`createdAt`	string (date-time)	When the top-up was recorded.
`methodName`	string	The payment method you used.
`currency`	string	Currency of the cent amounts. Always `USD`.
`paidCents`	integer	Amount paid, in US cents.
`feeCents`	integer	Fees taken off, in US cents.
`creditedCents`	integer	Amount added to your wallet, in US cents.
`originalCurrency`	string	Currency you paid in (ISO 4217).
`originalAmountMinor`	integer or null	Amount in the smallest unit of originalCurrency; null for USD.
`rejectReason`	string	Why we didn't accept the top-up; empty otherwise.

Errors

Code	HTTP status	Meaning
`invalid_api_key`	401	The API key is missing, malformed, revoked or no longer valid.
`account_action_required`	403	Sign in to the portal and finish the required account steps first.
`api_not_enabled`	403	API access is not enabled for this account.
`insufficient_scope`	403	The API key does not have the permission this call needs.
`validation_failed`	422	The input is not valid. `details` lists each field and the reason.
`rate_limited`	429	Too many requests. Wait for the number of seconds in Retry-After.
`internal_error`	500	Unexpected error. Quote X-Request-Id when you contact support.

Handle errors by code. See Errors.

curlNode.jsPython

curl 'https://api.rephut.com/v1/wallet/top-ups?page=1' \
  -H "Authorization: Bearer $FULFILLBOT_API_KEY"

const response = await fetch("https://api.rephut.com/v1/wallet/top-ups?page=1", {
  headers: {
    Authorization: `Bearer ${process.env.FULFILLBOT_API_KEY}`,
  },
});
const result = await response.json();
console.log(response.status, result);

import os

import requests

response = requests.get(
    "https://api.rephut.com/v1/wallet/top-ups?page=1",
    headers={
        "Authorization": f"Bearer {os.environ['FULFILLBOT_API_KEY']}",
    },
    timeout=30,
)
print(response.status_code, response.json())

Response 200

{
  "success": true,
  "data": [
    {
      "id": "cm3t0p0u0001rch9z8y7x6w5",
      "status": "CONFIRMED",
      "statusLabel": "Credited",
      "paidOn": "2026-11-02",
      "createdAt": "2026-11-02T08:15:30.000Z",
      "methodName": "Bank transfer",
      "currency": "USD",
      "paidCents": 100000,
      "feeCents": 0,
      "creditedCents": 100000,
      "originalCurrency": "USD",
      "originalAmountMinor": null,
      "rejectReason": ""
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 50,
    "pageCount": 1
  }
}

Transaction kinds

Value	Meaning
`RECHARGE`	Top-up: A top-up was credited to your wallet.
`RECHARGE_VOID`	Top-up void: An approved top-up was reversed.
`GOODS_DEBIT`	Goods payment: Payment for goods, for example a purchase order paid from your wallet.
`GOODS_REFUND`	Goods refund: Goods money returned to your wallet, for example when a purchase order is cancelled, goods arrive short, or a wallet payment is voided.
`GOODS_REFUND_VOID`	Refund reversal: A goods refund was reversed.
`SHIPPING_DEBIT`	Shipping: Shipping charged for an order when it was weighed.
`SURCHARGE`	Surcharge: Extra shipping charged after the order shipped, when the carrier bills a higher weight than we charged.
`ADJUST`	Adjustment: A manual adjustment by our team; `note` explains it.
`HANDLING_DEBIT`	Handling fee: Handling fee charged for an order.
`SHIPPING_REFUND`	Shipping refund: Shipping money returned to your wallet.
`HANDLING_REFUND`	Handling refund: Handling fee returned to your wallet.
`SHIPMENT_DEBIT`	Shipment payment: Payment for a shipment from your stock.
`SHIPMENT_REFUND`	Shipment refund: Shipment money returned to your wallet.
`SHIPMENT_REFUND_VOID`	Shipment refund reversal: A shipment refund was reversed.
`SURCHARGE_VOID`	Surcharge reversal: A surcharge was reversed.

Top-up statuses

Value	Meaning
`PENDING`	Waiting for us to check the payment.
`CONFIRMED`	Approved and credited to your wallet.
`REJECTED`	Not accepted; `rejectReason` says why.
`VOIDED`	Approved earlier, then reversed.

Webhook wallet.top_up_approved tells you when a top-up is approved (Webhook events).