Cost sharing and carrier fees

Cost sharing is how Surplus records agreed per-pound and flat rates (and, on routes, a share of carrier fees) for collections and distributions. Those rates feed invoicing to donors and recipients. The product uses the term “cost sharing” for these rates; invoice line items may still read in ordinary dollar terms.

Cost share agreements (CSAs)

A cost share agreement is a contract record tied to a donor or recipient organization. It holds:

• Invoice contact — legal name, billing email, and mailing address used when generating invoices (all required fields must be present before invoicing).
• Default rates — optional per-pound and flat amounts used when a specific collection or distribution does not override them.
• Memorandum of understanding — optional attachment path for the MOU or similar document.
• Additional invoice CCs — extra email addresses copied on billing messages (the primary billing address remains the agreement’s main email).

There are two parallel types:

Invoicing currently requires exactly one active CSA per partner: if an organization has multiple agreements in the system, consolidate or resolve which agreement applies before creating invoices.

Where rates apply: collections and distributions

• Route collections (driver pickup stops) use the donor’s CSA defaults unless you set a stop-level override for that event.
• Route distributions (driver delivery stops) use the recipient’s CSA defaults unless you set a stop-level override.
• Hub collections and hub distributions (food dropped off or picked up at a warehouse without using a route vehicle for that event) follow the same CSA rules for per-pound and flat components. They are not tied to a route for that event, which matters for carrier fees (see below).

How rates are resolved

For each completed event, Surplus resolves per-pound, flat, and carrier fee coverage in this order:

1. Stop override — optional values saved on the collection or distribution when editing the route stop (or when creating the stop). Any field you leave unset on the override falls through to the next level.
2. CSA defaults — defaultPerLbRate and defaultFlatRate on the donor or recipient agreement.
3. No rate — if no default applies, that component is omitted.

Explicit zero means the rate is waived for that component. Null on an override means “use the CSA default” for that field.

Overrides can also carry a note for internal documentation (for example, why a one-off rate was used).

Carrier fee coverage on a stop

On route collections and distributions, each stop can specify what fraction of the route’s carrier fee should count toward cost sharing for that stop. This is stored as a coverage rate between 0 and 100% (internally 0–1): it multiplies the route carrier fee to produce a carrier fee share for the line that gets invoiced.

Hub-only collections and distributions have no route for that event (routeId is unset). There is no route carrier fee attached to them, so the carrier fee share for invoicing is zero, even if a coverage percentage is set — there is nothing to multiply.

Route carrier fee

The carrier fee is a single optional dollar amount stored on the route (not on each stop). It represents the contracted logistics charge for that route, when your program tracks it for billing.

• Set or edit it when creating or editing route details (admins).
• Valid amounts must fall within the platform’s configured min/max range.
• When you remove the carrier fee from the route, any “awaiting fees” flag is cleared as well.

Awaiting fees

Turn on Awaiting fees when you know a carrier charge will apply but the dollar amount is not known yet (for example, awaiting the carrier’s invoice). While this is on, you should still enter the actual fee once it is finalized.

Invoicing guardrail: any offsite (route-based) collection or distribution on a route with Awaiting fees still on cannot be included in an invoice. The route must be updated with the real carrier fee (or the awaiting state resolved) before those events are billable. Hub-only events are not blocked by a route’s awaiting-fees flag in the same way, because they do not use that route’s carrier fee.

When building or reviewing invoices, the preview will list events that are blocked for this reason so you can fix the route first.

Practical checklist for admins

1. Organization setup — Ensure the donor or recipient has a CSA with complete invoice contact fields and the agreed default rates (if any).
2. Route execution — Enter the carrier fee when known; use Awaiting fees only as a temporary placeholder until the amount is confirmed.
3. Exceptions — Use per-stop overrides on pickup or delivery stops when a single stop needs different rates or carrier coverage than the CSA default.
4. Before invoicing — Complete all events, resolve awaiting fees on any routes that carry billable stops, and confirm the partner has a single CSA selected for billing.

Related guides

• Managing routes — creating routes, stops, and route detail (where carrier fee is set).
• Hub collections — onsite donor drop-offs (CSA applies; no route carrier fee for that event).
• Hub distributions — onsite recipient pickups (same pattern).