# 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](https://docs.rephut.com/developers/charges) 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](https://docs.rephut.com/developers/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](https://docs.rephut.com/developers/errors).

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

```js example=node
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);
```

```python example=python
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())
```

```json example=response status=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](https://docs.rephut.com/developers/pagination). From 1 to 10,000. Default: `1`. |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/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](https://docs.rephut.com/developers/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](#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](https://docs.rephut.com/developers/errors).

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

```js example=node
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);
```

```python example=python
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())
```

```json example=response status=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](https://docs.rephut.com/developers/pagination). From 1 to 10,000. Default: `1`. |

### Headers

| Header | Required | Value |
|---|---|---|
| `Authorization` | Yes | `Bearer <your API key>`. See [Authentication](https://docs.rephut.com/developers/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](https://docs.rephut.com/developers/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](#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](https://docs.rephut.com/developers/errors).

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

```js example=node
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);
```

```python example=python
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())
```

```json example=response status=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](https://docs.rephut.com/developers/webhooks/events)).