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

# List Mobile Top-Ups

> Get paginated list of mobile top-up transactions

## Overview

Returns a paginated list of all mobile top-up transactions for your account with optional date filtering.

## Query Parameters

<ParamField query="page" type="integer" default={1}>
  Page number (minimum: 1)
</ParamField>

<ParamField query="pageSize" type="integer" default={20}>
  Items per page (minimum: 1, maximum: 100)
</ParamField>

<ParamField query="from" type="string">
  Start date filter (ISO 8601: `2025-10-01T00:00:00Z`)
</ParamField>

<ParamField query="to" type="string">
  End date filter (ISO 8601: `2025-10-31T23:59:59Z`)
</ParamField>

<Note>
  Both `from` and `to` must be provided together when filtering by date.
</Note>

## Response

<ResponseField name="success" type="boolean" required>
  Indicates if the request was successful
</ResponseField>

<ResponseField name="data" type="object" required>
  <Expandable title="properties">
    <ResponseField name="items" type="array" required>
      Array of top-up objects with full details including status and amounts
    </ResponseField>

    <ResponseField name="pagination" type="object" required>
      <Expandable title="properties">
        <ResponseField name="page" type="integer">
          Current page number
        </ResponseField>

        <ResponseField name="pageSize" type="integer">
          Number of items per page
        </ResponseField>

        <ResponseField name="totalPages" type="integer">
          Total number of pages
        </ResponseField>

        <ResponseField name="totalResults" type="integer">
          Total number of top-ups
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object" required>
  <Expandable title="properties">
    <ResponseField name="timestamp" type="string">
      Response timestamp in ISO 8601 format
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.oneclickdz.com/v3/mobile/list?page=1&pageSize=20 \
    -H "X-Access-Token: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.oneclickdz.com/v3/mobile/list?page=1&pageSize=20",
    { headers: { "X-Access-Token": "YOUR_API_KEY" } }
  );
  const { data } = await response.json();
  console.log(data.items, data.pagination);
  ```

  ```python Python theme={null}
  response = requests.get(
      'https://api.oneclickdz.com/v3/mobile/list',
      headers={'X-Access-Token': 'YOUR_API_KEY'},
      params={'page': 1, 'pageSize': 20}
  )
  items = response.json()['data']['items']
  pagination = response.json()['data']['pagination']
  ```

  ```php PHP theme={null}
  <?php
  $url = 'https://api.oneclickdz.com/v3/mobile/list?page=1&pageSize=20';
  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-Access-Token: YOUR_API_KEY']);
  $response = json_decode(curl_exec($ch), true);
  $items = $response['data']['items'];
  ?>
  ```
</CodeGroup>

### Response Example

```json theme={null}
{
  "success": true,
  "data": {
    "items": [
      {
        "ref": "API-+213665983439-test-1761698196315-suggest",
        "status": "REFUNDED",
        "plan_code": "PREPAID_DJEZZY",
        "MSSIDN": "0600000002",
        "topup_amount": 500,
        "balance_amount": 0,
        "created_at": "2025-10-29T00:36:36.385Z",
        "_id": "69016194e9e88196b4eb64ce",
        "refund_message": "هذا رقم الهاتف لا يقبل العرض المرسل، الرجاء إرسال أحد العروض التالية",
        "suggested_offers": [
          {
            "typename": "📋 FACTURE | فاتورة",
            "plan_code": "FACTURE_DJEZZY",
            "amount": 500
          }
        ]
      },
      {
        "ref": "API-+213665983439-test-1761698175883-refund",
        "status": "REFUNDED",
        "plan_code": "PREPAID_DJEZZY",
        "MSSIDN": "0600000001",
        "topup_amount": 500,
        "balance_amount": 0,
        "created_at": "2025-10-29T00:36:15.952Z",
        "_id": "6901617fe9e88196b4eb64c7",
        "refund_message": "رقم الهاتف خاطئ يرجى التحقق منه"
      },
      {
        "ref": "API-+213665983439-test-1761698159224-success",
        "status": "FULFILLED",
        "plan_code": "PREPAID_DJEZZY",
        "MSSIDN": "0778037340",
        "topup_amount": 500,
        "balance_amount": 0,
        "created_at": "2025-10-29T00:35:59.378Z",
        "_id": "6901616fe9e88196b4eb64b0"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 5,
      "totalPages": 72,
      "totalResults": 358
    }
  },
  "meta": {
    "timestamp": "2025-10-29T00:36:47.159Z"
  }
}
```

## Use Cases

<CardGroup cols={2}>
  <Card title="Transaction History" icon="clock-rotate-left">
    Display top-up history to users
  </Card>

  <Card title="Reports & Analytics" icon="chart-line">
    Generate sales reports and statistics
  </Card>

  <Card title="Reconciliation" icon="scale-balanced">
    Verify transactions and balance changes
  </Card>

  <Card title="Customer Support" icon="headset">
    Look up user transactions for support
  </Card>
</CardGroup>

## Filtering Examples

### By Date Range

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.oneclickdz.com/v3/mobile/list?from=2025-10-01T00:00:00Z&to=2025-10-31T23:59:59Z" \
    -H "X-Access-Token: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const from = "2025-10-01T00:00:00Z";
  const to = "2025-10-31T23:59:59Z";

  const response = await fetch(
    `https://api.oneclickdz.com/v3/mobile/list?from=${from}&to=${to}`,
    { headers: { "X-Access-Token": "YOUR_API_KEY" } }
  );
  ```

  ```python Python theme={null}
  response = requests.get(
      'https://api.oneclickdz.com/v3/mobile/list',
      headers={'X-Access-Token': 'YOUR_API_KEY'},
      params={
          'from': '2025-10-01T00:00:00Z',
          'to': '2025-10-31T23:59:59Z',
          'page': 1,
          'pageSize': 50
      }
  )
  ```
</CodeGroup>

### Client-Side Filtering

```javascript theme={null}
const { items } = data;

// Filter by status
const fulfilled = items.filter((t) => t.status === "FULFILLED");
const refunded = items.filter((t) => t.status === "REFUNDED");

// Filter by operator
const djezzy = items.filter((t) => t.plan_code.includes("DJEZZY"));

// Filter by amount range
const large = items.filter((t) => t.topup_amount >= 1000);

// Calculate totals
const totalAmount = items.reduce((sum, t) => sum + t.topup_amount, 0);
const totalCost = items.reduce((sum, t) => sum + t.balance_amount, 0);
const profit = totalAmount - totalCost;
```

## Best Practices

<AccordionGroup>
  <Accordion title="Efficient Pagination">
    * Use reasonable page sizes (20-50 items)
    * Cache results when possible
    * Implement "Load More" or infinite scroll
    * Use `pagination.totalPages` to determine if there are more pages
  </Accordion>

  {" "}

  <Accordion title="Date Filtering">
    * Always provide both `from` and `to` - Use proper ISO 8601 format - Consider
      user's timezone when filtering - Set reasonable date ranges for performance
  </Accordion>

  {" "}

  <Accordion title="Performance">
    * Cache list data for short periods - Use date filters to limit result sets -
      Avoid fetching all pages at once - Index by created\_at in your local database
  </Accordion>

  <Accordion title="Display to Users">
    * Show status with icons/colors
    * Format timestamps in local timezone
    * Display operator logos
    * Link to detailed status pages
    * Show refund reason for failed top-ups
  </Accordion>
</AccordionGroup>

## Related Endpoints

<CardGroup cols={3}>
  <Card title="Send Top-Up" icon="paper-plane" href="/en/api-reference/mobile/send-topup">
    Create new top-up
  </Card>

  <Card title="Check Status" icon="magnifying-glass" href="/en/api-reference/mobile/check-by-ref">
    Track specific top-up
  </Card>

  <Card title="List Plans" icon="list" href="/en/api-reference/mobile/list-plans">
    View available plans
  </Card>
</CardGroup>