# Create Allocation Configuration

Create a new allocation configuration with rules.

Important: The total allocation percentage does NOT need to equal 100% at creation time.
This allows for incremental household enrollment. Validation of 100% happens at charge creation time.

Rule Types:
- RESPONSIBLE_PARTY - Split by percentage (e.g., Mom 50%, Dad 50%)
- COVERAGE_TRANSFER - Fixed amount covered (e.g., subsidy covers $25 per charge)
- BILLING_CAP - Maximum amount per period (e.g., subsidy covers up to $400/month)

Processing Order: Rules are processed in priority order (1 = first).
COVERAGE_TRANSFER and BILLING_CAP typically run before RESPONSIBLE_PARTY.

Endpoint: POST /allocationConfigurations
Version: 1.0.0
Security: OAuth2

## Request fields (application/json):

  - `name` (string, required)

  - `description` (string)

  - `rules` (array, required)

  - `rules.priority` (integer, required)

  - `rules.ruleType` (string, required)
    Type of allocation rule
    Enum: "RESPONSIBLE_PARTY", "COVERAGE_TRANSFER", "BILLING_CAP"

  - `rules.accountId` (string, required)

  - `rules.percentage` (number)

  - `rules.fixedAmount` (integer)

  - `rules.capAmount` (integer)

  - `rules.capPeriod` (string)
    Period for billing cap calculation
    Enum: "DAILY", "WEEKLY", "MONTHLY"

  - `rules.remainderHandling` (string)
    How to handle remainder amounts after cap
    Enum: "DISTRIBUTE_PROPORTIONALLY", "ASSIGN_TO_PRIMARY", "LEAVE_UNALLOCATED"

## Response 201 fields (application/json):

  - `id` (string, required)

  - `entityId` (string, required)

  - `name` (string, required)

  - `description` (string)

  - `version` (integer, required)
    Business version number for allocation configuration history

  - `effectiveFrom` (string)

  - `rules` (array, required)

  - `rules.priority` (integer, required)
    Processing order (1 = first)

  - `rules.ruleType` (string, required)
    Type of allocation rule
    Enum: "RESPONSIBLE_PARTY", "COVERAGE_TRANSFER", "BILLING_CAP"

  - `rules.accountId` (string, required)
    Reference to Account in Profile Service

  - `rules.percentage` (number)
    For RESPONSIBLE_PARTY rules

  - `rules.fixedAmount` (integer)
    For COVERAGE_TRANSFER rules (in cents)

  - `rules.capAmount` (integer)
    For BILLING_CAP rules (in cents)

  - `rules.capPeriod` (string)
    Period for billing cap calculation
    Enum: "DAILY", "WEEKLY", "MONTHLY"

  - `rules.remainderHandling` (string)
    How to handle remainder amounts after cap
    Enum: "DISTRIBUTE_PROPORTIONALLY", "ASSIGN_TO_PRIMARY", "LEAVE_UNALLOCATED"

  - `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"]