commissions

Code
Mark multiple commission payments as exported with timestamp.

Permission (BC-22436): commission export is a money-moving action -- when an
active ACH_ISSUANCE instance is configured it creates disbursement attempts
and dispatches ACH issuance through the engine. Guard it with the same
resources that expose the export UI (the pending-commission-payments and
agency-commissions surfaces); a user needs `rw` on EITHER to export.

Args:
    commission_payment_ids (Union[list, str]): List of commission payment IDs or "all"
    is_electronic_payment (bool): Optional filter for electronic vs manual payments
    commission_month (str): Optional YYYY-MM filter (only used when
        commission_payment_ids == "all"; scopes "Process All Eligible" to the
        operator's filtered grid view).
    status (str): Optional status filter ("all" export only).
    search (dict): Optional {type, value} search filter ("all" export only).

Returns:
    dict: Operation result with the total number of payments processed, the
        number the funding gate blocked, the number left in the queue
        unissued (``total_deferred``) and the operator-facing reasons for
        those (``messages``) -- an export that issues nothing is a success
        response, so the UI needs the reasons to avoid reporting it as a
        completed payment run (BC-25115).

Code
Mark multiple commission payments as reviewed with timestamp.

Args:
    commission_payment_ids (list): List of commission payment ID strings

Returns:
    dict: Operation results containing success/failure counts and details.
    Data includes total_processed, total_succeeded, and total_failed counts.

Code
Update payment method for multiple commission payments.

Args:
    payments (list): List of payment dictionaries with keys:
        - commission_payment_id (str): ID of the commission payment
        - is_electronic_payment (bool): Payment method type

Returns:
    dict: Operation results containing success/failure counts and details.
    Data includes total_processed, total_succeeded, and total_failed counts.

Code
Create a single commission accounting adjustment.

Supports two shapes (BC-23072):
- source-ful: pass ``source_accounting_id`` to copy from an existing
  accounting record (existing behavior).
- source-less: omit ``source_accounting_id`` and instead supply
  ``agency_id`` + ``agent_id`` + ``adjustment_amount`` + ``period_start`` /
  ``period_end`` + a non-blank ``adjustment_reason`` (``reason_code``
  optional) for an agency-level commission chargeback.

Permission (BC-23072): the source-less shape books money against a
caller-supplied agency/agent, so the endpoint requires `rw` on EITHER
`britecore/policies/pendingCommissionPayments` or
`britecore/policies/agency-commissions` -- the same resource pair that
guards the sibling batch_export_payments commission write surface.

Args:
    source_accounting_id (str): ID of the source accounting record to copy from
    adjustment_reason (str): Reason for the adjustment, stored in
        commission_accounting.why; REQUIRED for a source-less adjustment
        (must be non-blank and at most 150 characters, measured on the
        submitted value and rejected rather than truncated when longer),
        optional on the source-ful path
    adjustment_amount (float): Amount of the adjustment
    reason_code (str): Quick-code reason (COMMISSION_ADJUSTMENT_REASONS) to stamp;
        optional (defaults to the quick-code default on the source-less path)
    agency_id (str): Agency (payee); REQUIRED for a source-less adjustment,
        ignored on the source-ful path
    agent_id (str): Agent; REQUIRED for a source-less adjustment,
        ignored on the source-ful path
    period_start (str): Period start (ISO datetime); REQUIRED for a source-less adjustment
    period_end (str): Period end (ISO datetime); REQUIRED for a source-less
        adjustment. Snapped to the END OF ITS MONTH (last day, 23:59:59) and
        the snapped value is stored as the row's transaction date. The month
        is chosen AFTER conversion to America/Chicago, so a UTC instant just
        past midnight on the 1st (e.g. 2026-08-01T00:00:00Z) lands in the
        PREVIOUS month (July 31, not August 31).

Returns:
    dict: Operation results containing adjustment details.
    If new commission payments are created due to policy calculation,
    data will also include 'new_payment_ids' list.

Deletes commission payments in batch

Code
Parameters
----------
payment_ids : list
    BriteCore commission_payment id UUIDs

Returns
-------
success : bool
    True if completely successful, false if not
messages : list of str
    List of human-readable error messages

Deletes single commission payment

Code
Parameters
----------
payment_id : str, required
    A BriteCore commission_payment id UUID

Returns
-------
success : bool
    True if completely successful, false if not
messages : list of str
    List of human-readable error messages

Code
Download commission PDF reports for agencies and agency groups.

Automatically rebuilds any reports that are determined to be out of date
before delivering them to the user. For agency group contacts, retrieves
reports for all agencies in the group.

Parameters
----------
contacts : list, required
    List of dictionaries each containing an 'id' and a 'role' key.
    Role must be either 'agency' or 'agency_group'.
    Example: [{"id": 123, "role": "agency"}, {"id": 456, "role": "agency_group"}]
report : str, required
    Type of report to retrieve. Must be 'standard' or 'negative'.
    'standard' requires year and month parameters.
    'negative' uses current date automatically.
year : str, optional
    Required for 'standard' reports only. The year for which the report was generated.
    Example: "2024"
month : str, optional
    Required for 'standard' reports only. The month for which the report was generated.
    Must be full month name (e.g., "January", "February", etc.)

Returns
-------
dict
    Response with success status and delivery information.
    For download method: includes download URL.
    For email method: includes success confirmation message.

Code
Zip commission PDF reports and email a presigned download link to the admin.

Args:
    payload (dict)
Returns:
    dict: Response with success status and queued confirmation message.

Code
Email commission PDF reports for agencies and agency groups.

Args:
    payload (dict)
Returns:
    dict: Operation results containing email confirmation.
    Response with success status and email confirmation message.

Code
Get commission accounting entries with optional filtering.

Args:
    agent_id (str): Optional agent ID filter
    policy_id (str): Optional policy ID filter
    item_id: Optional item ID filter (can be None or NOT_PROVIDED)
    commission_payment_id (str): Optional commission payment ID filter
    page (int): Optional page number for pagination (default: 1)
    page_size (int): Optional page size for pagination (default: 25)

Returns:
    dict: Commission accounting entries data with pagination and totals

Special item_id handling:
    - If item_id is not provided: no filtering on item_id
    - If item_id is provided as null: filter for records where item_id IS NULL

Retrieves a list of payees agency numbers

Code
Returns
-------
success : bool
    True if completely successful, false if not
messages : list of str
    List of human-readable error messages
data : list of str
    Contains agency numbers of valid commission payees

Code
Get commission payment composition aggregated by agent_id, policy_id, and item_id.

Args:
    commission_payment_id (str): Optional commission payment ID filter
    agency_id (str): Optional agency ID filter
    filters (dict): Optional additional filters
    page (int): Optional page number for pagination (default: 1)
    page_size (int): Optional page size for pagination (default: 25)

Returns:
    dict: Commission payment composition data with agencies and aggregated entries

Code
Get commission payments with filtering and pagination.

Args:
    commission_month (str): Filter by commission month in YYYY-MM format
    status (str): Filter by status - 'pending', 'reviewed', or 'exported'
    is_electronic_payment (bool): Filter by electronic payment flag
    search (dict): Search parameters with 'type' and 'value' keys
    page (int): Page number for pagination (default: 1)
    page_size (int): Number of items per page (default: 20)

Returns:
    dict: Commission payments data with pagination and summary

Code
Get detailed delayed commission accounting entries (with commission_payment_id=NULL).

Returns:
    dict: Detailed delayed commission entries including:
        - entries: List of delayed commission accounting entries
        - total_entries: Total count of delayed entries
        - total_commissionable_amount: Sum of all commissionable amounts
        - total_amount_to_be_paid: Sum of all amounts to be paid
        - inserted_by_contacts: Contact identifiers for inserted_by fields

Code
Get summary of delayed commission accounting entries (with commission_payment_id=NULL).

Returns:
    dict: Summary of delayed commission entries including:
        - total_entries: Total count of delayed entries
        - delayed_breakdown: Count by delayed column value

Gets a commission payment record.

Code
Parameters
----------
commission_payment_id : str, required
    A BriteCore commission_payment id UUID

Returns
-------
success : bool
    True if completely successful, false if not
messages : list of str
    List of human-readable error messages
data : dict
    A dict containing the following data representation. ::
        {
            commission_payments.pay_amount (DECIMAL)
            commission_payments.date_updated (TIMESTAMP)
            commission_payments.is_electronic_payment (BOOLEAN)
            commission_payments.payee_id (CHAR(36))
            commission_payments.reviewed (BOOLEAN)
            commission_payments.date_reviewed (DATETIME)
            commission_payments.transaction_date (DATETIME)
            commission_payments.exported (BOOLEAN)
            commission_payments.date_added (DATETIME)
            commission_payments.date_exported (DATETIME)
            commission_payments.id (CHAR(36))
            commission_payments.payment_method_id (CHAR(36))
            commission_payments.check_number (INT, nullable)
            commission_payments.check_date (DATETIME, nullable)
            commission_payments.cleared_date (DATETIME, nullable)
        }

Code
Poll the status of an async commission statements regeneration job
started via ``regenerate_statements``. Identified by the target
report month, which is all the server needs -- the reference_id
that ``regenerate_statements`` returns is a deterministic hash of
the month, so exposing it on the poll endpoint would be redundant
(and an extra piece of client-side state to manage across page
reloads).

Args:
    year (int, optional): See ``regenerate_statements``. Must be
        supplied together with ``month``.
    month (int, optional): See ``regenerate_statements``. Must be
        supplied together with ``year``.

    When both ``year`` and ``month`` are omitted, defaults to the
    month immediately preceding the current month -- the natural
    "what's running right now for the normal use case?" query used
    by the page-refresh recovery path.

Returns:
    dict: ``{'success': bool, 'async_status': str, 'async_result': any,
             'reference_id': <uuid>, 'year': int, 'month': int}``.
        ``async_status`` is one of ``'in_progress'``, ``'success'``,
        ``'failure'``, or ``'not_found'``. ``success`` is ``False``
        only when the job reached a terminal failure state. The
        echoed ``year`` / ``month`` let the caller preserve the
        resolved month across the start-then-poll handoff -- this
        prevents a month-rollover race for clicks that land
        seconds before midnight on the last day of the month.

Code
Retrieve all commissions that are not exported

Parameters
----------

Returns
-------
success : bool
data : a list of dicts
{
  "pay_amount": decimal,
  "payment_method": {
    "address_line2": str,
    "masked_routing": str,
    "address_line1": str,
    "vendor": str,
    "address_city": str,
    "masked_number": str,
    "name_on_account": str,
    "account_description": str,
    "method": str,
    "address_state": str,
    "account_type": str,
    "address_country": str,
    "account_name": str,
    "address_zip": str
  },
  "id": str,
  "payee": {
    "phones": [
      {
        "phone": str,
        "type": str
      }
    ],
    "producer_number": str,
    "agency_number": str,
    "agency_group_number": str,
    "confirmation_email": str,
    "addresses": [
      {
        "address_line2": str,
        "address_city": str,
        "address_line1": str,
        "type": str,
        "address_state": str,
        "address_country": str,
        "address_zip": str
      }
    ],
    "name": str
  },
  "transaction_date": datetime,
  "composition": [
    {
      "commission_rate": decimal,
      "commissionable_amount": decimal,
      "amount_to_be_paid": decimal,
      "policy": {
        "policy_number_normalized": str,
        "policy_number": str
      },
      "revision": {
        "policy_status": str,
        "primary_property": {
          "address_line2": str,
          "address_city": str,
          "address_line1": str,
          "name": str,
          "address_state": str,
          "address_country": str,
          "address_zip": str
        },
        "revision_state": str
      }
    }
  ]
}
messages : list
    empty

Code
Asynchronously regenerate all monthly commission statements for the
specified month. Replaces the synchronous
``/gateway?file=policies.commissions&method=reRunCommissionStatements``
call made by the *Regenerate Statement* button on
*Policies > Payments > Pending Commission Payments*, which blocks the
HTTP worker for the full duration of every agency's PDF render and is
prone to timeouts on carriers with hundreds of agencies.

The heavy work runs in a Celery task
(``RegenerateCommissionStatementsAsyncView``). The caller receives a
``reference_id`` immediately and polls ``get_regenerate_statements_status``
to drive the UI. Repeat clicks for the same month collapse onto the
same in-flight BackgroundJob row rather than queueing duplicates.

Args:
    year (int, optional): Four-digit calendar year of the report
        month (e.g. ``2026``). Must be supplied together with
        ``month``.
    month (int, optional): Calendar month of the report
        month, 1-12. Must be supplied together with ``year``.

    When both ``year`` and ``month`` are omitted, defaults to the
    month immediately preceding the current month (the normal
    "regenerate last month's statements" flow).

Returns:
    dict: ``{'success': True, 'async_status': 'in_progress',
             'async_result': None, 'reference_id': <uuid>,
             'year': int, 'month': int}``.
        The ``reference_id`` is a deterministic UUID derived from the
        report month so it is stable across retries and page reloads;
        it surfaces in logs / Datadog / the BackgroundJob row and is
        useful for support investigations but not required for
        polling (the status endpoint identifies the job by
        ``year`` + ``month``). The echoed ``year`` / ``month`` let
        the caller preserve the resolved month across the start-then-
        poll handoff even around month-rollover boundaries.

Saves commission payments in batch

Code
Parameters
----------
payments : list
    A list of dicts with the keys ``agency_number`` and ``amount``.

    ``agency_number`` should correspond with a single BriteCore agency.

    ``amount`` should be a decimal representation of a monetary amount to be paid.

Returns
-------
success : bool
    True if completely successful, false if not
messages : list of str
    List of human-readable error messages
data : list of dict
    Contains important information about the inserted records.
    ::

        {
            'commission_payment_id': commission_payment.id,
            'payment_method_id': commission_payment.payment_method_id,
            'agency_id': commission_payment.payee_id,
            'amount': commission_payment.pay_amount
        }

Saves commission payments in batch

Code
Parameters
----------
data : str, required
    A string representation of a csv file. Entries should map agency_number
    to a respective amount used to create a commission payment record.
    Agency numbers can appear more than once on the input csv, and must
    refer to one and only one contact (i.e. an agency number cannot be used
    on the csv if two contacts can be reached by this number). Any value
    convertible to a python float is acceptable., including 0.

    Example 1 (with csv header row):
        agency_number,amount
        T34514,11207.12
        T34515,15000.00
        T34516,12120.55
        T34514,720.00
        T34516,720.00

    Example 2 (without csv header row):
        A0001,0.00
        A0002,14.00

Returns
-------
success : bool
    True if completely successful, false if not
messages : list of str
    List of human-readable error messages
data : list of dict
    Contains important information about the inserted records.
    ::

        {
            'commission_payment_id': commission_payment.id,
            'payment_method_id': commission_payment.payment_method_id,
            'agency_id': commission_payment.payee_id,
            'amount': commission_payment.pay_amount
        }

Saves commission payment

Code
Parameters
----------
agency_number : str
    A BriteCore agency contact id UUID
amount : decimal
    Should be a decimal representation of a monetary amount to be paid

Returns
-------
success : bool
    True if completely successful, false if not
messages : list of str
    List of human-readable error messages
data: list of dict
    Contains important information about the inserted record. ::

        {
            'commission_payment_id': commission_payment.id,
            'payment_method_id': commission_payment.payment_method_id,
            'agency_number': commission_payment.payee_id,
            'amount': commission_payment.pay_amount
        }

Clear a select list of payments from the commission queue

Code
Parameters
----------
commission_payment_ids : list, required
    Pass a list of CommissionPayment IDs. These CommissionPayments will be marked as
    exported and reviewed

Returns
-------
success : bool
    True if completely successful, false if not
messages : list of str
    List of human-readable error messages

Code
Write off all delayed negative commission accounting entries for an entire agency.
Creates one offsetting entry per policy (aggregating amounts across items).

This API addresses delayed commission entries by agency. It:
1. Finds all entries with delayed='neg_amt' and comm_pay_id=NULL for the agency
2. Groups entries by policy
3. Creates one offsetting commission accounting entry per policy (aggregated)
4. Creates a single $0 commission payment for the entire agency write-off
5. Links all entries to the commission payment
6. Updates all entries' delayed status to 'not_delayed'
7. Records the write-off reason on all entries

Args:
    agency_id (str): The agency ID to write off all negative entries for
    write_off_reason (str): The reason for write-off:
        - 'collected_from_agency': Balance was collected from the agency
        - 'forgiven': Balance was forgiven/written off
    why (str): User-provided description/reason for the write-off (stored in commission_accounting.why)

Returns:
    dict: Write-off result with agency info, payment ID, totals, and per-policy results