# Create Rate

Create a new rate in the pricing catalog.

Rate Types:
- service fee - Regular service fee/service fees
- LATE_FEE - Late payment penalties
- REGISTRATION - One-time registration fees
- DISCOUNT - Discount rates (use discountPercentage instead of pricePerUnit)
- OTHER - Miscellaneous charges

Endpoint: POST /rates
Version: 1.0.0
Security: OAuth2

## Request fields (application/json):

  - `description` (string, required)

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

  - `pricePerUnit` (integer)
    Required unless type is DISCOUNT

  - `discountPercentage` (number)
    Required if type is DISCOUNT

  - `tags` (object)

## Response 201 fields (application/json):

  - `id` (string, required)
    Unique identifier

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

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

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

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

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

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

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

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

  - `createdAt` (string, required)

  - `updatedAt` (string)

## Response 400 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 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"]