# List Rates

List all rates (pricing catalog) for the authenticated merchant with pagination and filtering.
Rates define how much each type of service costs.

Endpoint: GET /rates
Version: 1.0.0
Security: OAuth2

## Query parameters:

  - `type` (string)
    Filter by rate type
    Enum: "service fee", "LATE_FEE", "REGISTRATION", "DISCOUNT", "OTHER"

  - `tags` (string)
    Filter by tags using dot.notation (key:value pairs, comma-separated)
    Example: "billing.program:PRE_K,billing.taxable:false"

  - `page` (integer)
    Page number (1-indexed)
    Example: 1

  - `page_size` (integer)
    Number of items per page
    Example: 50

## Response 200 fields (application/json):

  - `results` (array, required)

  - `results.id` (string, required)
    Unique identifier

  - `results.entityId` (string, required)
    Merchant identifier (from auth context)

  - `results.description` (string, required)
    Human-readable description of the rate

  - `results.type` (string, required)
    Type of rate
    Enum: "service fee", "LATE_FEE", "REGISTRATION", "DISCOUNT", "OTHER"

  - `results.pricePerUnit` (integer)
    Price per unit in cents (e.g., 5000 = $50.00). Required unless type is DISCOUNT.

  - `results.discountPercentage` (number)
    Discount percentage (only for type DISCOUNT)

  - `results.tags` (object)
    Tags for categorization and reporting

  - `results.version` (integer)
    Business version number for audit history and deterministic billing (auto-incremented on updates)

  - `results.optimisticLockVersion` (integer)
    Optimistic locking version (managed by Hibernate @Version). Prevents concurrent update conflicts.

  - `results.createdAt` (string, required)

  - `results.updatedAt` (string)

  - `pagination` (object, required)

  - `pagination.totalRecords` (integer, required)
    Total number of records across all pages
    Example: 100

  - `pagination.currentPage` (integer, required)
    Current page number (1-indexed)
    Example: 1

  - `pagination.totalPages` (integer, required)
    Total number of pages
    Example: 10

  - `pagination.nextPage` (integer,null)
    Next page number, null if on last page
    Example: 2

  - `pagination.prevPage` (integer,null)
    Previous page number, null if on first page

## Response 401 fields (application/json):

  - `result` (object, required)

  - `result.status` (string, required)
    Response status (always ERROR for error responses)
    Enum: "ERROR"

  - `error` (object, required)

  - `error.responseCode` (string, required)
    Response code (numeric or contains numbers, e.g., "404", "409", "500", "ERR001")
    Example: "404"

  - `error.responseMessage` (array, required)
    Array of error message strings for multiple error details
    Example: ["Charge not found","The requested charge ID does not exist in the system"]

## Response 429 fields (application/json):

  - `result` (object, required)

  - `result.status` (string, required)
    Response status (always ERROR for error responses)
    Enum: "ERROR"

  - `error` (object, required)

  - `error.responseCode` (string, required)
    Response code (numeric or contains numbers, e.g., "404", "409", "500", "ERR001")
    Example: "404"

  - `error.responseMessage` (array, required)
    Array of error message strings for multiple error details
    Example: ["Charge not found","The requested charge ID does not exist in the system"]