🔍 Problem Statement

As an operations administrator, I calculate every carrier's pay outside Pelcro, which makes billing slow, unauditable, and disconnected from actual delivery data.

Carriers (vendors) can already be assigned deliveries through delivery zones and fulfillments, and bills can be created manually. What is missing is a standardized way to calculate the amount owed to each carrier based on actual delivery performance:

1. A configurable billing rate per successful delivery.

2. A configurable deduction per missed issue/delivery.

3. A reliable way to calculate delivered and missed quantities from fulfillment data.

4. Protection against route ownership changes (e.g., when a route changes carriers during a billing period).

5. A centralized process to generate bills for all carriers in a billing cycle.

💡 User Story

1. As an operations administrator, I want to select a billing cycle and generate bills for all participating carriers in one run, so that payouts are accurate and repeatable.

2. As an operations administrator, I want to state carrier rates in plain language, so that rates need no new configuration screens.

🎯 Definition of Done (DoD)

✔ Given an admin selects a cycle start and end date, when the bill job runs, then it fetches fulfillments approved inside that window, derives the participating vendors, and generates one bill per vendor.

✔ Given delivered and missed quantities for a cycle, when the bill is calculated, then Net Amount = (Delivered Quantity × Delivery Rate) − (Missed Issues × Missed Issue Rate).

✔ Given a carrier rate written as an AI Plan pricing rule, when the job runs, then the AI Billing Agent resolves the rate and returns required attributes.

✔ Given rates vary by route, when rules are written, then each rate is its own plan and the admin is responsible for assigning the correct plan to each vendor.

✔ Given a bill is generated, when an admin opens it, then it shows cycle window, carrier, rates applied, delivered quantity, missed quantity, total deductions, and net payable.

✔ Given a bill is generated, when it is audited later, then the fulfillments included in that bill are recorded and retrievable.

✔ Given a bill already exists for a carrier and cycle, when the job reruns, then duplicate bills are prevented.

✔ Given a route changed carrier mid-cycle, when bills are generated, then each fulfillment is attributed to the carrier assigned at the time that fulfillment occurred.

✔ This solution will include the following limitations: Payable path only; approved fulfillments only, consistent with the agent's approved-shipments-only rule; operator-triggered runs with no platform schedule; no tax or multi-currency on carrier bills; missed-delivery capture scoped in a separate task.