# Charges

Manage billable charges (mutable pre-invoice state)

## List Charges

 - [GET /charges](https://docs.nelnetpay.com/apis/billing-ledger-service/charges/listcharges.md): List charges (mutable pre-invoice state) for the authenticated merchant.

Status Filtering:
- PENDING - Created but not validated
- BILLED - Ready to invoice
- VOID - Cancelled

Charges with status INVOICED or PAID are in the SettledCharges table.

## Create Charge

 - [POST /charges](https://docs.nelnetpay.com/apis/billing-ledger-service/charges/createcharge.md): 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.

## Get Charge Details

 - [GET /charges/{chargeId}](https://docs.nelnetpay.com/apis/billing-ledger-service/charges/getcharge.md): Retrieve details of a specific charge

## Update Charge

 - [PATCH /charges/{chargeId}](https://docs.nelnetpay.com/apis/billing-ledger-service/charges/updatecharge.md): Update a charge (partial update).

Restrictions: Only charges with status PENDING or BILLED can be updated.
Once a charge is INVOICED, it becomes immutable (moved to SettledCharges).

## Delete Charge

 - [DELETE /charges/{chargeId}](https://docs.nelnetpay.com/apis/billing-ledger-service/charges/deletecharge.md): Delete a charge (hard delete for PENDING, soft delete/void for BILLED).

Restrictions: Cannot delete charges with status INVOICED or PAID.
Use ledger adjustments for corrections to invoiced charges.

## Void Charge

 - [POST /charges/{chargeId}/void](https://docs.nelnetpay.com/apis/billing-ledger-service/charges/voidcharge.md): Void a charge (sets status to VOID).

Use Case: When a charge was created in error but you want to keep audit trail.

## Create Multiple Charges

 - [POST /charges/bulk](https://docs.nelnetpay.com/apis/billing-ledger-service/charges/createchargesbulk.md): Create multiple charges in a single request.

Use Case: Creating charges for multiple billable entities at once (e.g., batch from recurring billing).

Atomicity: All charges are created in a single transaction. If any fails, all are rolled back.