# Create Charge

Create a new charge for a billable entity.

Validation at Creation:
1. Fetches all accounts associated with billableEntityId (via Profile Service)
2. Validates billableEntity is associated with ALL accounts in allocationConfig
3. Validates allocationConfig covers 100% of ALL accounts for the billableEntity
4. Returns 422 if validation fails

Charge Calculation:
- amount = quantity × rate.pricePerUnit
- proratedAmount = amount × prorationFactor
- netAmount = proratedAmount - sum(discountAmounts)

Idempotency: Include Idempotency-Key header to prevent duplicate charges.

Endpoint: POST /charges
Version: 1.0.0
Security: OAuth2

## Header parameters:

  - `Idempotency-Key` (string)
    Unique key to ensure idempotent operations (UUID recommended)

## Request fields (application/json):

  - `billableEntityId` (string, required)

  - `subscriptionId` (string)

  - `rateId` (string, required)

  - `quantity` (number, required)

  - `prorationFactor` (number)

  - `allocationConfigId` (string, required)

  - `discountRateIds` (array)

  - `overrideAllocation` (object)

  - `eventDate` (string, required)

  - `tags` (object)

## Response 201 fields (application/json):

  - `id` (string, required)

  - `entityId` (string, required)

  - `billableEntityId` (string, required)

  - `accountId` (string)
    Primary account for this charge (from allocation)

  - `subscriptionId` (string,null)
    Subscription that generated this charge (if any)

  - `rateId` (string, required)

  - `quantity` (number, required)

  - `amount` (integer, required)
    Amount in cents BEFORE discounts

  - `prorationFactor` (number)
    Proration factor (e.g., 0.5 for half month)

  - `proratedAmount` (integer)
    Amount after proration (in cents)

  - `netAmount` (integer, required)
    Final amount after discounts (in cents)

  - `discountRateIds` (array)

  - `discountAmounts` (array)
    Discount amounts in cents (parallel to discountRateIds)

  - `allocationConfigId` (string, required)

  - `overrideAllocation` (object)
    Manual allocation override (optional)

  - `status` (string, required)
    Status of mutable charge
    Enum: "PENDING", "BILLED", "VOID"

  - `eventDate` (string, required)
    Date of the event that generated this charge

  - `rateVersion` (integer)
    Version of rate when charge was created

  - `subscriptionVersion` (integer)
    Version of subscription when charge was created

  - `allocationVersion` (integer)
    Version of allocation config when charge was created

  - `discountRateVersions` (array)
    Versions of discount rates when charge was created (parallel to discountRateIds)

  - `tags` (object)

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