# List Charges

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.

Endpoint: GET /charges
Version: 1.0.0
Security: OAuth2

## Query parameters:

  - `status` (string)
    Filter by charge status
    Enum: "PENDING", "BILLED", "VOID"

  - `billable_entity_id` (string)
    Filter by billable entity ID

  - `account_id` (string)
    Filter by account ID

  - `event_date_from` (string)
    Filter charges with event date on or after this date

  - `event_date_to` (string)
    Filter charges with event date on or before this date

  - `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)

  - `results.entityId` (string, required)

  - `results.billableEntityId` (string, required)

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

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

  - `results.rateId` (string, required)

  - `results.quantity` (number, required)

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

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

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

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

  - `results.discountRateIds` (array)

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

  - `results.allocationConfigId` (string, required)

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

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

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

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

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

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

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

  - `results.tags` (object)

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