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

# Read APIs

> Read a user account, payment methods, orders, refunds, and purchase authorizations with a portal token.

All read APIs use the portal user token from [Portal token](https://docs.clinkbill.com/api-reference/agent-portal/portal_token.md). They are read-only and scoped to the token's `sub` customer.

## Authentication

```http theme={null}
Authorization: Bearer {PORTAL_TOKEN}
```

The gateway verifies `aud=clink-agent-platform-portal`, `scope=portal:read`, and `token_use=access`, then passes the verified customer identity to cwallet. There is no request parameter for selecting a different customer or email.

Clink responses use the standard envelope:

```json theme={null}
{
  "code": 200,
  "msg": "Success",
  "data": {}
}
```

The examples below show `data`.

## Common behavior

* `pageNum` and `pageSize` use 1-based pagination.
* Order lists accept `status`, `from`, and `to` filters.
* Lists are scoped to the customer, not to an Agent. Orders, refunds, and authorizations created by any Agent for that customer are returned.
* A missing record, or a record owned by another customer, is returned as `404`.
* There are no write endpoints in this API.

## Get account

```http theme={null}
GET {API_BASE_URL}/agent/platform/me
```

```json theme={null}
{
  "customer_id": "ccus_...",
  "email": "user@example.com",
  "name": "Example User",
  "country": "US",
  "status": "READY"
}
```

| Field | Meaning |
| - | - |
| `customer_id` | Clink customer ID. |
| `email` | Customer email. |
| `name` | Customer display name. |
| `country` | Billing address country, when available. |
| `status` | Wallet readiness: `READY`, `NOT_READY`, or `SUSPENDED`. `NOT_READY` means the account exists but has no usable default payment method. |

## List payment methods

```http theme={null}
GET {API_BASE_URL}/agent/platform/payment-methods
```

```json theme={null}
{
  "payment_methods": [
    {
      "payment_instrument_id": "pi_...",
      "payment_method_type": "CARD",
      "payment_instrument_type": "VIRTUAL_CARD",
      "card_scheme": "VISA",
      "card_last_four": "4242",
      "expiry_month": "12",
      "expiry_year": "2030",
      "issuer_bank": "Example Bank",
      "is_default": true,
      "status": "ACTIVE"
    }
  ]
}
```

`status` is `ACTIVE` or `DISABLED`. PAN and CVV are never returned.

## List orders

```http theme={null}
GET {API_BASE_URL}/agent/platform/orders?pageNum=1&pageSize=20&status={STATUS}&from={ISO_DATE}&to={ISO_DATE}
```

| Parameter | Required | Meaning |
| - | - | - |
| `pageNum` | No | Page number, starting at 1. |
| `pageSize` | No | Page size. |
| `status` | No | Order status filter. |
| `from` | No | Inclusive lower time bound. |
| `to` | No | Inclusive upper time bound. |

```json theme={null}
{
  "total": 2,
  "page_num": 1,
  "page_size": 20,
  "truncated": false,
  "records": [
    {
      "order_id": "order_...",
      "paid_time": "2026-01-01T00:00:00Z",
      "amount": 42.5,
      "currency": "USD",
      "display_amount": "$42.50",
      "status_code": 1,
      "status": "SUCCESS",
      "merchant_name": "Example Merchant",
      "payment_method_type": "CARD",
      "payment_method_label": "Visa •••• 4242",
      "payment_method_icon": "https://...",
      "payment_instrument_last_four": "4242",
      "agent_info": {
        "clientId": "agent_..."
      }
    }
  ]
}
```

`truncated: true` means the status/time filtered scan reached Clink's internal scan bound; `total` describes the records scanned, not necessarily the customer's complete matching history. Without filters, the endpoint reads one page and does not use the bounded scan.

## Get order

```http theme={null}
GET {API_BASE_URL}/agent/platform/orders/{orderId}
```

The detail response includes order time, amount breakdown, merchant, payment method, card scheme, products, shipping address and amount, `agent_info`, and a `refund_summary`:

```json theme={null}
{
  "order_id": "order_...",
  "order_time": "2026-01-01T00:00:00Z",
  "amount": 42.5,
  "display_amount": "$42.50",
  "subtotal_amount": 40.0,
  "display_subtotal_amount": "$40.00",
  "currency": "USD",
  "status_code": 1,
  "status": "SUCCESS",
  "merchant_name": "Example Merchant",
  "merchant_url": "https://merchant.example",
  "payment_method_type": "CARD",
  "payment_method_label": "Visa •••• 4242",
  "payment_instrument_last_four": "4242",
  "card_scheme": "VISA",
  "credit_amount": 2.5,
  "display_credit_amount": "$2.50",
  "paid_amount": 42.5,
  "display_paid_amount": "$42.50",
  "products": [],
  "agent_info": {},
  "refund_summary": {
    "refund_count": 0,
    "refunded_amount": 0,
    "currency": "USD",
    "latest_status": null,
    "refunds": []
  }
}
```

## List refunds

```http theme={null}
GET {API_BASE_URL}/agent/platform/refunds?pageNum=1&pageSize=20
```

```json theme={null}
{
  "total": 1,
  "page_num": 1,
  "page_size": 20,
  "records": [
    {
      "refund_order_id": "refund_...",
      "order_id": "order_...",
      "refund_amount": 10.0,
      "refund_currency": "USD",
      "status": "SUCCESS",
      "refund_reason": "Customer request",
      "payment_instrument_id": "pi_..."
    }
  ]
}
```

## Get refund

```http theme={null}
GET {API_BASE_URL}/agent/platform/refunds/{refundOrderId}
```

Returns one refund with the fields shown above. A refund owned by another customer is returned as `404`.

## List authorizations

```http theme={null}
GET {API_BASE_URL}/agent/platform/authorizations?pageNum=1&pageSize=20&status={STATUS}
```

| Parameter | Required | Meaning |
| - | - | - |
| `pageNum` | No | Page number, starting at 1. |
| `pageSize` | No | Page size. |
| `status` | No | Authorization status filter. |

```json theme={null}
{
  "total": 1,
  "page_num": 1,
  "page_size": 20,
  "records": [
    {
      "instruction_id": "inst_...",
      "client_reference_id": "platform-ref-1",
      "payment_instrument_id": "pi_...",
      "card_last_four": "4242",
      "card_type": "VIRTUAL_CARD",
      "card_scheme": "VISA",
      "title": "Example authorization",
      "description": "Purchase authorization",
      "total_amount_limit": 100.0,
      "currency_code": "USD",
      "effective_until_time": "2026-02-01T00:00:00Z",
      "is_recurring": false,
      "status": "ACTIVE",
      "agent_info": {},
      "mandates": [],
      "usages": []
    }
  ]
}
```

## Get authorization

```http theme={null}
GET {API_BASE_URL}/agent/platform/authorizations/{instructionId}
```

The detail response includes the instruction fields, `mandates`, and `usages`. `usages` are raw usage records; compute used and remaining amounts from them when rendering the portal. An instruction owned by another customer is returned as `404`.

## Errors

| HTTP status | Meaning |
| - | - |
| `400` | Invalid query parameters. |
| `401` | Missing, expired, or invalid portal token. |
| `403` | Wrong token audience, wrong scope, or a platform client token used instead of a portal token. |
| `404` | Record not found or not owned by the token's customer. |
| `429` | Rate limit exceeded. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.