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

# List Branches

> Returns branches with stable UUIDs, optionally filtered by merchant

<Info>
  Returns branches visible to your API key, sorted alphabetically by name.
</Info>

## Filtering by Merchant

Use `merchant_id` to get branches for a specific merchant:

```
GET /v1/branches?merchant_id=57846d47-d196-5c48-a881-4003b1d5aa98
```

Omit `merchant_id` to get all branches visible to your key.

## Using Branch IDs

Use the `branch_id` from this endpoint to filter transactions:

```bash theme={null}
# 1. Get branches
GET /v1/branches
# Response: [{"id": "f3febca6-...", "name": "Main Street", "merchant_id": "57846d47-..."}, ...]

# 2. Filter transactions by branch
GET /v1/transactions?branch_id=f3febca6-7bd2-5d10-bcd7-1f796088e90c
```

## Next Steps

<CardGroup cols={2}>
  <Card title="List Merchants" icon="store" href="/api-reference/transaction-reporting/list-merchants">
    Get merchant UUIDs to filter branches
  </Card>

  <Card title="List Transactions" icon="list" href="/api-reference/transaction-reporting/list-transactions">
    Filter transactions by branch\_id
  </Card>
</CardGroup>


## OpenAPI

````yaml api-reference/transaction-reporting/openapi.json GET /v1/branches
openapi: 3.0.3
info:
  title: Transaction Reporting API
  description: >-
    Unified REST API for querying transaction history across all payment
    methods. Provides entity-scoped data isolation with cursor-based pagination.


    **Entity Hierarchy:** Partner → Merchant → Branch → Terminal → Transaction.
    All data access is scoped to the authenticated API key's entity level.


    **Cursor Pagination:** All list endpoints use opaque cursor-based
    pagination. Default page size is 20, maximum is 100.


    **Sorting:** Transactions can be sorted by `created_at` (default),
    `updated_at`, or `amount` in ascending or descending order.


    **Unified Response Model:** All transactions use the same `amount_details`
    schema regardless of payment method. The canonical GTV field is
    `amount_received`.
  version: 1.1.0
  contact:
    name: API Support
    email: support@moduluslabs.io
  license:
    name: Proprietary
servers:
  - url: https://api.sbx.moduluslabs.io/reports
    description: Sandbox
security:
  - ApiKeyAuth: []
tags:
  - name: Transactions
    description: Transaction queries and reporting
  - name: Entities
    description: Merchant and branch listing
  - name: Health
    description: Health check endpoints
paths:
  /v1/branches:
    get:
      tags:
        - Entities
      summary: List branches
      description: |-
        Returns branches . Optionally filtered by merchant_id.
        Entity-scoped and sorted by name.
      operationId: listBranches
      parameters:
        - $ref: '#/components/parameters/MerchantId'
      responses:
        '200':
          description: Branch list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BranchListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  parameters:
    MerchantId:
      name: merchant_id
      in: query
      required: false
      description: >
        Filter by logical merchant UUID from the Merchant Registry.

        Works cross-DB — returns transactions from both databases if the
        merchant exists in both.
      schema:
        type: string
        format: uuid
  schemas:
    BranchListResponse:
      type: object
      required:
        - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Branch'
    Branch:
      type: object
      required:
        - id
        - name
        - merchant_id
      properties:
        id:
          type: string
          format: uuid
          description: Stable logical branch UUID.
        name:
          type: string
        merchant_id:
          type: string
          format: uuid
          description: Parent merchant logical UUID.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: Both database circuit breakers are open, or registry unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >
        API key for authentication. Verified by APISIX via Vanguard.

        APISIX injects identity headers and strips the raw key before
        forwarding.

````