> ## Documentation Index
> Fetch the complete documentation index at: https://docs.standalonetech.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API Reference

> Programmatic access to wallet balances, transactions, top-ups, transfers and admin tools via the terawallet/v1 REST API.

TeraWallet ships a first-class REST API under the **`terawallet/v1`** namespace. It powers the
plugin's own React dashboard and admin screens, and is fully available to your own apps and
integrations.

<Note>
  The older `wc/v3/wallet/*` routes still exist as a **deprecated** back-compatibility layer and
  will be removed in a future major release. New integrations should target **`terawallet/v1`**.
</Note>

## Base URL

```
https://your-store.com/wp-json/terawallet/v1/
```

## Authentication

Endpoints are grouped by who may call them, and each group uses the matching auth method:

| Group             | Path prefix                   | Who                                               | Authentication                                                           |
| ----------------- | ----------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------ |
| Customer          | `me/*`                        | The logged-in customer (acts on their own wallet) | WordPress cookie + REST nonce (same-origin), e.g. an `X-WP-Nonce` header |
| Admin             | `admin/*`                     | Users with the `manage_woocommerce` capability    | Cookie + nonce, or WooCommerce **Consumer Key / Secret** (Basic Auth)    |
| Settings / System | `settings/*`, `system/*`      | `manage_woocommerce`                              | Cookie + nonce, or Consumer Key / Secret                                 |
| Public            | `public/*`, `settings/public` | Anyone                                            | None                                                                     |

For external/server-to-server calls, generate keys under **WooCommerce → Settings → Advanced →
REST API** and send them as HTTP Basic Auth.

### Idempotency

State-changing customer endpoints (`POST me/topup`, `POST me/transfer`) and admin bulk
operations honor an **`Idempotency-Key`** request header. Send a unique key (e.g. a UUID) per
logical action; a retry with the same key replays the original response instead of creating a
duplicate top-up, transfer, or credit. Keys are scoped per user with a 24-hour TTL.

***

## Customer endpoints (`me/*`)

### Get balance

```
GET /terawallet/v1/me/balance
```

Returns the current user's balance. The response is multi-currency aware: `amount` is in the
active storefront currency, while `base_*` fields are always normalized to the shop base currency.

```json theme={null}
{
  "amount": 250.00,
  "currency": "USD",
  "formatted": "$250.00",
  "base_currency": "USD",
  "base_amount": 250.00,
  "base_formatted": "$250.00",
  "mode": "single_base",
  "balances": [
    { "currency": "USD", "amount": 250.00, "formatted": "$250.00" }
  ]
}
```

| Field                               | Description                                                                |
| ----------------------------------- | -------------------------------------------------------------------------- |
| `amount` / `currency` / `formatted` | Balance in the active storefront currency.                                 |
| `base_amount` / `base_currency`     | Total wallet value normalized to the shop base currency.                   |
| `mode`                              | `single_base` or `per_currency` (see [multi-currency](#system-endpoints)). |
| `balances[]`                        | Per-currency sub-balances; always at least one entry.                      |

### List transactions

```
GET /terawallet/v1/me/transactions
GET /terawallet/v1/me/transactions/{id}
```

Paginated ledger history for the current user.

| Query arg          | Type    | Notes                                       |
| ------------------ | ------- | ------------------------------------------- |
| `page`, `per_page` | integer | Standard pagination.                        |
| `orderby`          | string  | `date`, `amount`, or `transaction_id`.      |
| `order`            | string  | `asc` or `desc`.                            |
| `type`             | string  | Filter by `credit` or `debit`.              |
| `category`         | string  | Filter by transaction category (see below). |

Each row exposes a typed **`category`**, one of: `topup`, `cashback`, `cashback_adjustment`,
`cashback_refund`, `partial_payment`, `transfer`, `refund`, `adjustment`, `other`.

### Create a top-up

```
POST /terawallet/v1/me/topup
```

Creates a top-up order and returns a payment URL to redirect the customer to.

| Body field       | Type   | Required | Notes                                               |
| ---------------- | ------ | -------- | --------------------------------------------------- |
| `amount`         | number | Yes      | Minimum `0.01`.                                     |
| `payment_method` | string | No       | A WooCommerce gateway id (e.g. `stripe`).           |
| `currency`       | string | No       | ISO 4217 code; charges the top-up in that currency. |

```json theme={null}
{
  "order_id": 1234,
  "amount": 50.00,
  "currency": "USD",
  "payment_url": "https://your-store.com/checkout/order-pay/1234/?pay_for_order=true&key=wc_order_..."
}
```

<Tip>
  Send an `Idempotency-Key` header so a double-submit (or a network retry) returns the original
  order instead of creating a second top-up.
</Tip>

### Transfer funds

```
POST /terawallet/v1/me/transfer
GET  /terawallet/v1/me/transfer/recipients
```

Send wallet balance to another registered user. Provide **either** `recipient_id` **or**
`recipient_email`.

| Body field        | Type    | Required        | Notes                                                  |
| ----------------- | ------- | --------------- | ------------------------------------------------------ |
| `recipient_id`    | integer | One of id/email | Recipient user id.                                     |
| `recipient_email` | string  | One of id/email | Recipient account email.                               |
| `amount`          | number  | Yes             | Subject to the configured min/max and transfer charge. |
| `note`            | string  | No              | Optional message stored on both ledger legs.           |
| `currency`        | string  | No              | Optional ISO 4217 code.                                |

The `recipients` route returns a lookup list for an autocomplete picker (gated by a filter).

### Other customer reads

| Endpoint                               | Returns                                                                |
| -------------------------------------- | ---------------------------------------------------------------------- |
| `GET /terawallet/v1/me`                | Profile snapshot with wallet summary and related links.                |
| `GET /terawallet/v1/me/referrals`      | The customer's referral share URL, visitor/signup counts and earnings. |
| `GET /terawallet/v1/me/cashback-rules` | The cashback rules currently active for this customer/cart.            |

***

## Admin endpoints (`admin/*`)

Require the `manage_woocommerce` capability.

### Transactions

```
GET    /terawallet/v1/admin/transactions
POST   /terawallet/v1/admin/transactions
GET    /terawallet/v1/admin/transactions/{id}
PATCH  /terawallet/v1/admin/transactions/{id}
DELETE /terawallet/v1/admin/transactions/{id}?force=true
POST   /terawallet/v1/admin/transactions/bulk
```

List supports `page`, `per_page`, `orderby` (`id`, `transaction_id`, `date`, `amount`,
`currency`, `type`, `user_id`), `order`, and `type` filters.

Create a manual credit or debit:

```json theme={null}
{
  "user_id": 42,
  "type": "credit",
  "amount": 10.00,
  "details": "Goodwill credit"
}
```

`DELETE` performs a soft delete by default; pass `?force=true` for a permanent delete. The
`bulk` route accepts an `action` of `credit`, `debit`, or `delete` and is idempotent per user.

### Users

```
GET  /terawallet/v1/admin/users
GET  /terawallet/v1/admin/users/{id}
POST /terawallet/v1/admin/users/{id}/lock
POST /terawallet/v1/admin/users/{id}/unlock
```

List users with their balances, read a single user, and lock/unlock a wallet to block further
spending (useful for fraud holds).

### Admin transfer

```
POST /terawallet/v1/admin/transfer
```

Move balance between two users on the customer's behalf.

***

## Settings & system endpoints

| Endpoint                                  | Description                                                         |
| ----------------------------------------- | ------------------------------------------------------------------- |
| `GET /terawallet/v1/settings`             | Fetch all plugin settings.                                          |
| `POST /terawallet/v1/settings/section`    | Save a settings section (`section_id` + fields).                    |
| `POST /terawallet/v1/settings/js-section` | Save a JS-registered settings tab (sanitized per server whitelist). |
| `GET /terawallet/v1/system/multicurrency` | Active currency provider, base/active currencies and ledger mode.   |
| `GET /terawallet/v1/settings/public`      | Unauthenticated public settings (e.g. cashback rules).              |

<Info>
  All responses are JSON. Send `Content-Type: application/json` on requests with a body, and an
  `Idempotency-Key` header on top-ups, transfers and bulk operations.
</Info>

## Legacy namespace (deprecated)

The `wc/v3/wallet/*` routes from earlier versions remain as thin proxies for back-compatibility
and emit the same row shapes as their `terawallet/v1` equivalents. **Do not build new
integrations against them** — migrate to `terawallet/v1`.