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

# Get Operations

> Retrieve a paginated list of merchant operations (cash-in, cash-out, pay-merchant, pay-individual)

## Endpoint

```
GET /api/v1/merchants/{merchantID}/operations
```

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer token with your API key. Must have **Read Transactions** permission.
</ParamField>

## Path Parameters

<ParamField path="merchantID" type="string" required>
  The unique identifier of the merchant. Must match the merchant ID associated with the API key.
</ParamField>

## Query Parameters

<ParamField query="limit" type="integer" default="100">
  Maximum number of operations to return. Maximum value: 1000.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of operations to skip for pagination.
</ParamField>

## Response

Returns an array of operation objects, sorted by creation date (newest first).

<ResponseField name="operations" type="array">
  <Expandable title="Operation Object">
    <ResponseField name="operationID" type="string">
      Unique identifier for the operation
    </ResponseField>

    <ResponseField name="merchantID" type="string">
      Merchant identifier
    </ResponseField>

    <ResponseField name="operationType" type="string">
      Type of operation: `cash-in`, `cash-out`, `pay-merchant`, or `pay-individual`
    </ResponseField>

    <ResponseField name="amount" type="string">
      Transaction amount as decimal string
    </ResponseField>

    <ResponseField name="fee" type="string">
      Fee charged for the operation (if applicable)
    </ResponseField>

    <ResponseField name="distributorTo" type="string">
      Distributor ID (for `cash-out` operations, or source distributor for `cash-in`)
    </ResponseField>

    <ResponseField name="distributorName" type="string">
      Distributor name (resolved from distributor ID)
    </ResponseField>

    <ResponseField name="merchantTo" type="string">
      Destination merchant ID (for `pay-merchant` operations)
    </ResponseField>

    <ResponseField name="merchantName" type="string">
      Destination merchant name (for `pay-merchant` operations)
    </ResponseField>

    <ResponseField name="phoneTo" type="string">
      Recipient phone number (for `pay-individual` operations)
    </ResponseField>

    <ResponseField name="memo" type="string">
      Optional reference note or description
    </ResponseField>

    <ResponseField name="blockchainID" type="string">
      Blockchain transaction identifier (empty if still processing)
    </ResponseField>

    <ResponseField name="sequenceNumber" type="integer | null">
      Blockchain sequence number (if submitted)
    </ResponseField>

    <ResponseField name="lastError" type="string | null">
      Last error message if operation failed
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/operations?limit=10&offset=0" \
    -H "Authorization: Bearer uwk_YOUR_API_KEY_HERE"
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const response = await axios.get(
    'https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/operations',
    {
      params: {
        limit: 10,
        offset: 0
      },
      headers: {
        'Authorization': 'Bearer uwk_YOUR_API_KEY_HERE'
      }
    }
  );

  console.log('Operations:', response.data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.yourdomain.com/api/v1/merchants/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/operations',
      params={'limit': 10, 'offset': 0},
      headers={'Authorization': 'Bearer uwk_YOUR_API_KEY_HERE'}
  )

  print('Operations:', response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  [
    {
      "operationID": "op_8b7c9d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
      "merchantID": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "operationType": "cash-in",
      "amount": "50000.00",
      "fee": "0",
      "distributorTo": "36e48800-22ce-4ea0-b37a-198f7978cd53",
      "distributorName": "PAPSS Distributor",
      "memo": "Monthly deposit",
      "blockchainID": "tx_abc123...",
      "createdAt": "2026-02-12T10:30:00Z",
      "updatedAt": "2026-02-12T10:30:15Z"
    },
    {
      "operationID": "op_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "merchantID": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "operationType": "pay-individual",
      "amount": "3000.00",
      "fee": "50.00",
      "phoneTo": "+234 8123456781",
      "memo": "Refund for order #1234",
      "blockchainID": "tx_def456...",
      "createdAt": "2026-02-12T09:15:00Z",
      "updatedAt": "2026-02-12T09:15:20Z"
    },
    {
      "operationID": "op_2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
      "merchantID": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "operationType": "pay-merchant",
      "amount": "15000.00",
      "fee": "100.00",
      "merchantTo": "b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
      "merchantName": "Supplier Co.",
      "memo": "Wholesale payment",
      "blockchainID": "tx_ghi789...",
      "createdAt": "2026-02-11T14:00:00Z",
      "updatedAt": "2026-02-11T14:00:30Z"
    },
    {
      "operationID": "op_3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
      "merchantID": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "operationType": "cash-out",
      "amount": "20000.00",
      "fee": "200.00",
      "distributorTo": "36e48800-22ce-4ea0-b37a-198f7978cd53",
      "distributorName": "PAPSS Distributor",
      "blockchainID": "tx_jkl012...",
      "createdAt": "2026-02-10T16:30:00Z",
      "updatedAt": "2026-02-10T16:30:45Z"
    }
  ]
  ```

  ```json 403 Forbidden - Missing Permission theme={null}
  {
    "type": "/problems/access-forbidden",
    "status": 403,
    "title": "Access Forbidden",
    "detail": "API key does not have Read Transactions permission"
  }
  ```
</ResponseExample>

## Operation Types

<AccordionGroup>
  <Accordion title="cash-in">
    Funds received from a distributor. The `distributorTo` and `distributorName` fields identify the source distributor. Fee is always `0` for cash-in operations.
  </Accordion>

  <Accordion title="cash-out">
    Funds withdrawn to a distributor. The `distributorTo` and `distributorName` fields identify the destination distributor.
  </Accordion>

  <Accordion title="pay-merchant">
    Payment sent to another merchant. The `merchantTo` and `merchantName` fields identify the destination merchant.
  </Accordion>

  <Accordion title="pay-individual">
    Payment sent to an individual wallet. The `phoneTo` field identifies the recipient.
  </Accordion>
</AccordionGroup>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Get Balance" icon="wallet" href="/api-reference/merchants/get-balance">
    Check merchant balance before creating operations
  </Card>

  <Card title="Get Payments" icon="money-bill" href="/api-reference/merchants/get-payments">
    View incoming payments received by this merchant
  </Card>

  <Card title="Create Operation" icon="plus" href="/api-reference/merchants/create-operation">
    Create a new merchant operation
  </Card>
</CardGroup>