MedBridge Sales Ops Reconciliation
Reconcile CRM, quote, logistics, and milestone engagement data from the MedBridge Sales
Ops API into structured JSON decision packages. This skill covers three workflow families
that share the same API surface but apply different business logic.
Use the shared API base URL the runner provides. In prompts it appears as a placeholder
like <TASK_ENV_BASE_URL> or BASE_URL. Substitute it into every GET call below.
Quick dispatch
Read the prompt for the task shape and follow the matching workflow:
- The prompt names a quote ID starting with
Q-TR and asks for freight options →
go to Quote Revision with Freight.
- The prompt names an RFQ ID starting with
RFQ-TR, mentions "IEHK" modules, and
says EXW only or "no destination" →
go to Indicative Module RFQ.
- The prompt names an opportunity ID starting with
OPP-TR and asks for milestone
reconciliation, invoice matching, revenue recognition, or a contact name →
go to Engagement Reconciliation.
Any prompt that does not clearly match one shape is likely a near miss for this skill.
Read the prompt carefully before committing to a workflow.
Shared ground rules
- The API is read-only. All endpoints are
GET and return JSON with a records array
on collection endpoints or a single record object on detail endpoints.
- Every entity has a stable
id field. Use those exact values in output JSON.
- Money values are always in USD with two decimal places.
- Dates are ISO
YYYY-MM-DD. Use the quote date or "as of" date from the prompt;
if the prompt doesn't state one, default to 2026-06-01.
- When the prompt provides a customer ID, product code, opportunity ID, or quote ID,
call the matching detail endpoint, not just the collection list.
- Output must be pure JSON matching the answer template. No markdown wrapping.
1. Quote Revision with Freight Comparison
A customer confirmed a revised quantity for a product on an existing quote.
Return one JSON with quote summary, freight options, and policy flags.
API calls
Always make these calls, in this order:
GET /api/quotes/<quote_id> — confirms the quote record, customer ID, product
code, confirmed quantity, incoterm, prior pricing, and line-item notes.
GET /api/customers/<customer_id> — confirms customer type, segment,
payment_profile, recurring status, grant terms, and region. Use the
customer_id field from the quote response.
GET /api/products/<product_code> — confirms product name, article number,
price tiers, lead time, shelf life, and cold-chain flag. Use the
primary_product_code from the quote response.
GET /api/freight-quotes — lists all freight quotes. Filter client-side to
records whose quote_id field matches the quote ID.
GET /api/policies — confirms payment terms, freight reconfirmation, EXW
scope, and quote validity rules.
Catalog tier matching
The product record has a price_tiers array. Each tier defines min_qty,
max_qty (null means unlimited), unit_price_usd, lead_time_days, and
shelf_life_months. Find the tier where confirmed_quantity falls within
[min_qty, max_qty]. When the quote mentions a customer-confirmed quantity
that differs from the prior quote quantity, the catalog tier may override the
prior unit price — always source the price from the matching tier, not from
the prior quote.
Compute exw_total_usd = confirmed_quantity * unit_price_usd.
Freight option assembly
For each freight quote that matches the quote ID:
- Use the
id, mode (uppercased to AIR/SEA/ROAD), cost_usd, and
transit_days_text.
- Map
route_risk to a display value: low → "LOW", medium → "MEDIUM",
high → "HIGH".
- Set
risk_flag from risk_notes: if route_risk is low, "NONE";
for medium, reflect the concern (e.g. "MEDIUM_BORDER_RISK"); for high,
reflect the high-risk concern.
grand_total_usd = exw_total_usd + freight_cost_usd.
- Check
valid_until: a freight quote is stale when its valid_until date is
before the quote date. Mark it with "validity_status": "STALE" and
"source_is_stale": true.
When the output template asks for validity_status (like train_004's template),
add it. When the template only asks for valid_until, just use that field.
Policy and recommendation logic
- Payment terms come from the customer's
payment_profile field, cross-checked
against matching policy rules. For recurring customers, the policy
POL-RECURRING-NGO-PAYMENT or equivalent applies. For new clients,
POL-NEW-CLIENT-PAYMENT applies.
freight_reconfirmation_required is true because policy
POL-FREIGHT-RECONFIRM says rates need reconfirmation at final order.
all_freight_options_valid_on_quote_date: compare each freight quote's
valid_until against the quote date. If all are on or after the quote date,
set true; otherwise false.
- Recommended mode: prefer the lowest-cost valid option whose
route_risk
is low. SEA is often the winner for non-time-critical cargo. If the
prompt mentions delivery timing or a "need-by" date, factor transit days
into the recommendation. If all modes have some risk, default to the
cheapest with the least risk.
When the template includes client_warnings, generate a freight warning
summarizing any stale or high-risk options.
Ordering freight options
List in the order AIR, SEA, ROAD, matching the typical template order.
2. Indicative Module RFQ (EXW Only)
An RFQ requests indicative pricing for medical modules without a confirmed
destination, so freight is excluded and the quote is EXW only.
API calls
GET /api/rfqs/<rfq_id> — confirms the RFQ, customer ID, requested modules
with product_code and quantity per module, and request type.
GET /api/customers/<customer_id> — confirms customer type (new NGO vs
recurring), segment, and payment_profile.
- For each module in the RFQ's
requested_modules, call
GET /api/products/<product_code> to get the product name, article number,
unit price tier, lead time, and shelf life.
GET /api/policies — confirms module-level quoting policy
(POL-MODULE-GRANULARITY), EXW-only scope for indicative quotes without
destination (POL-INDICATIVE-EXW), quote validity (POL-QUOTE-VALIDITY),
and payment terms for new clients (POL-NEW-CLIENT-PAYMENT).
Module-level quoting
The RFQ narrative and the policy POL-MODULE-GRANULARITY both instruct quoting
at module level only, even when the API exposes component_composition_distractors
or product components arrays. Each RFQ module becomes one line item with the
module's product code, article number, quantity, and unit price.
When a product has a single price tier covering all quantities (min_qty 1,
max_qty null), use that tier directly. Multiply quantity by unit price for the
line total.
Payment terms for new NGOs
Check the customer's payment_profile. For "NEW_CLIENT_REVIEW" or similar,
apply PREPAY_100 per the new-client policy. For recurring customers with
NET_30_AFTER_PO, use that.
Quote validity
If the output template asks for offer_validity_days, use 30 calendar days
per POL-QUOTE-VALIDITY (standard catalog quote validity). For
who_documentation_required, set true when the RFQ involves medical modules
for an NGO — this is the safe default for humanitarian medical supply.
freight_excluded is always true for this workflow.
3. Engagement & Milestone Reconciliation
A won opportunity has milestone phases with associated invoices, payments,
revenue journals, events, and vouchers. Reconcile everything and produce
follow-up task instructions.
API calls
GET /api/opportunities/<opportunity_id> — confirms stage, won amount,
phases with phase IDs and amounts, contact, customer ID, and any notes.
GET /api/customers/<customer_id> — confirms customer name and details.
GET /api/invoices — filter client-side by opportunity_id to match the
opportunity's phases to their invoices.
GET /api/payments — filter by opportunity_id to see which invoices
have been paid.
GET /api/revenue-journals — filter by opportunity_id to see which
completed paid milestones have revenue recognition entries.
GET /api/events — find events whose opportunity_id matches. Use the
event's primary_contact and voucher_code details.
GET /api/vouchers/<voucher_code> — confirms voucher status, discount,
max uses.
GET /api/policies — confirms revenue recognition rule
(POL-REVREC), payment terms, and quote validity.
Cross-referencing logic
For each phase in the opportunity:
- Match the phase to its invoice via
invoice_id on the phase record.
- Match the invoice to payments: if
paid_amount_usd >= amount_usd, the
milestone is PAID; if paid_amount_usd > 0 but less than full, it is
PARTIAL; otherwise UNPAID.
- Match to revenue journals: look for a journal entry whose
phase_id
matches and whose status is "posted".
Revenue recognition status per milestone:
| Invoice paid? |
Revenue journal exists? |
Status |
| Yes |
Yes |
RECOGNIZED |
| Yes |
No |
MISSING_REVENUE_JOURNAL or REQUIRED_MISSING |
| No |
N/A |
NOT_REQUIRED_UNPAID |
Overall revenue recognition status:
- If every paid milestone has a revenue journal →
COMPLETE_FOR_PAID_MILESTONES
- If any paid milestone lacks a journal →
MISSING_FOR_PAID_MILESTONES
- If no milestones are paid →
NOT_REQUIRED
Opportunity-to-phase matching: sum all phase amounts and compare to
won_amount_usd. Set opportunity_matches_milestones or
opportunity_matches_phase_total to true when they are equal.
Outstanding balance: sum outstanding_amount_usd (or amount unpaid) across
all invoices for the opportunity.
Follow-up task routing
Produce exactly the tasks the data demands:
Collection tasks:
- If any milestone is unpaid with a due date on or before the as-of date, it
is overdue → action is
COLLECT_UNPAID_MILESTONE or SEND_COLLECTION_NOTICE,
owner queue is COLLECTIONS or ACCOUNT_MANAGEMENT.
- If unpaid but not yet due → action is
MONITOR_UNPAID_NOT_DUE, owner queue
is ACCOUNT_MANAGEMENT.
- If no unpaid milestones exist →
NO_COLLECTION_ACTION.
Revenue recognition tasks:
- If any paid milestone has
MISSING_REVENUE_JOURNAL → action is
RECORD_REVENUE_MS2 (or the specific milestone), debit DEFERRED_REVENUE,
credit IMPLEMENTATION_SERVICES_REVENUE, owner queue ACCOUNTING.
- If all paid milestones are recognized →
NO_ACCOUNTING_ACTION or
VERIFY_REVENUE_ONLY.
Event/invitation tasks:
- If an event exists with status
scheduled or confirmed and its
voucher is active → action is SEND_BRIEFING_INVITE or
SEND_EVENT_INVITATION, owner queue ACCOUNT_MANAGEMENT, contact
from the event's primary_contact field.
- If the event is in the past or completed →
NO_INVITE_ACTION.
Accounting action details
When a revenue recognition journal is missing for a paid milestone, produce
the accounting action entry:
action: RECORD_REVENUE_<milestone_id> (e.g. RECORD_REVENUE_MS2)
milestone_id: the specific milestone ID
amount: the milestone amount
debit_account: DEFERRED_REVENUE
credit_account: IMPLEMENTATION_SERVICES_REVENUE
owner_queue: ACCOUNTING
This mirrors the standard pattern from the revenue recognition policy.
Error handling
- If an API call returns an empty response or an error, verify the ID and
retry once. If it still fails, leave the corresponding output field empty
or at its null/zero default instead of guessing.
- If the prompt names an entity that does not exist in the API, return the
template with empty fields and include a
_note field explaining the
missing record.
Reference files
- references/policy-rules.md — Full list of
MedBridge policy rules and how they apply per workflow.
- references/reconciliation-patterns.md —
Detailed reconciliation decision tables for milestone, invoice, payment,
and revenue journal cross-referencing.
- references/field-mappings.md — API field to
template field mappings for each workflow's common template shapes.
Read a reference when the data demands more detail than the workflow section
above covers. The policy rules reference is especially useful when a task
mentions an unfamiliar policy area.
1---2name: medbridge-reconciliation-23description: Reconcile quotes, RFQs, engagements, and milestones against the MedBridge Sales Ops API to produce account-ready decision-package JSON. Use when the task references MedBridge, reconciliation, quote revision, freight comparison, IEHK or other module RFQs, milestone-to-invoice cross-referencing, revenue recognition journal verification, opportunity-to-phase matching, OR any MedBridge Sales Ops API endpoint. This covers freight-option EXW quotes, indicative module-level quoting, and opportunity-milestone engagement reconciliations with follow-up task routing.4metadata:5 source: https://skillmd.com/skills/prism-shadow/medbridge-reconciliation-26---78# MedBridge Sales Ops Reconciliation910Reconcile CRM, quote, logistics, and milestone engagement data from the MedBridge Sales11Ops API into structured JSON decision packages. This skill covers three workflow families12that share the same API surface but apply different business logic.1314Use the shared API base URL the runner provides. In prompts it appears as a placeholder15like `<TASK_ENV_BASE_URL>` or `BASE_URL`. Substitute it into every `GET` call below.1617## Quick dispatch1819Read the prompt for the task shape and follow the matching workflow:2021- **The prompt names a quote ID starting with `Q-TR` and asks for freight options** →22 go to [Quote Revision with Freight](#1-quote-revision-with-freight-comparison).23- **The prompt names an RFQ ID starting with `RFQ-TR`, mentions "IEHK" modules, and24 says EXW only or "no destination"** →25 go to [Indicative Module RFQ](#2-indicative-module-rfq-exw-only).26- **The prompt names an opportunity ID starting with `OPP-TR` and asks for milestone27 reconciliation, invoice matching, revenue recognition, or a contact name** →28 go to [Engagement Reconciliation](#3-engagement-milestone-reconciliation).2930Any prompt that does not clearly match one shape is likely a near miss for this skill.31Read the prompt carefully before committing to a workflow.3233## Shared ground rules3435- The API is read-only. All endpoints are `GET` and return JSON with a `records` array36 on collection endpoints or a single record object on detail endpoints.37- Every entity has a stable `id` field. Use those exact values in output JSON.38- Money values are always in USD with two decimal places.39- Dates are ISO `YYYY-MM-DD`. Use the quote date or "as of" date from the prompt;40 if the prompt doesn't state one, default to `2026-06-01`.41- When the prompt provides a customer ID, product code, opportunity ID, or quote ID,42 call the matching detail endpoint, not just the collection list.43- Output must be pure JSON matching the answer template. No markdown wrapping.4445## 1. Quote Revision with Freight Comparison4647A customer confirmed a revised quantity for a product on an existing quote.48Return one JSON with quote summary, freight options, and policy flags.4950### API calls5152Always make these calls, in this order:53541. `GET /api/quotes/<quote_id>` — confirms the quote record, customer ID, product55 code, confirmed quantity, incoterm, prior pricing, and line-item notes.562. `GET /api/customers/<customer_id>` — confirms customer type, segment,57 payment_profile, recurring status, grant terms, and region. Use the58 `customer_id` field from the quote response.593. `GET /api/products/<product_code>` — confirms product name, article number,60 price tiers, lead time, shelf life, and cold-chain flag. Use the61 `primary_product_code` from the quote response.624. `GET /api/freight-quotes` — lists all freight quotes. Filter client-side to63 records whose `quote_id` field matches the quote ID.645. `GET /api/policies` — confirms payment terms, freight reconfirmation, EXW65 scope, and quote validity rules.6667### Catalog tier matching6869The product record has a `price_tiers` array. Each tier defines `min_qty`,70`max_qty` (null means unlimited), `unit_price_usd`, `lead_time_days`, and71`shelf_life_months`. Find the tier where `confirmed_quantity` falls within72`[min_qty, max_qty]`. When the quote mentions a customer-confirmed quantity73that differs from the prior quote quantity, the catalog tier may override the74prior unit price — always source the price from the matching tier, not from75the prior quote.7677Compute `exw_total_usd = confirmed_quantity * unit_price_usd`.7879### Freight option assembly8081For each freight quote that matches the quote ID:8283- Use the `id`, `mode` (uppercased to AIR/SEA/ROAD), `cost_usd`, and84 `transit_days_text`.85- Map `route_risk` to a display value: `low` → `"LOW"`, `medium` → `"MEDIUM"`,86 `high` → `"HIGH"`.87- Set `risk_flag` from `risk_notes`: if route_risk is `low`, `"NONE"`;88 for `medium`, reflect the concern (e.g. `"MEDIUM_BORDER_RISK"`); for `high`,89 reflect the high-risk concern.90- `grand_total_usd = exw_total_usd + freight_cost_usd`.91- Check `valid_until`: a freight quote is stale when its `valid_until` date is92 before the quote date. Mark it with `"validity_status": "STALE"` and93 `"source_is_stale": true`.9495When the output template asks for `validity_status` (like train_004's template),96add it. When the template only asks for `valid_until`, just use that field.9798### Policy and recommendation logic99100- Payment terms come from the customer's `payment_profile` field, cross-checked101 against matching policy rules. For recurring customers, the policy102 `POL-RECURRING-NGO-PAYMENT` or equivalent applies. For new clients,103 `POL-NEW-CLIENT-PAYMENT` applies.104- `freight_reconfirmation_required` is `true` because policy105 `POL-FREIGHT-RECONFIRM` says rates need reconfirmation at final order.106- `all_freight_options_valid_on_quote_date`: compare each freight quote's107 `valid_until` against the quote date. If all are on or after the quote date,108 set `true`; otherwise `false`.109- **Recommended mode**: prefer the lowest-cost valid option whose `route_risk`110 is `low`. SEA is often the winner for non-time-critical cargo. If the111 prompt mentions delivery timing or a "need-by" date, factor transit days112 into the recommendation. If all modes have some risk, default to the113 cheapest with the least risk.114115When the template includes `client_warnings`, generate a freight warning116summarizing any stale or high-risk options.117118### Ordering freight options119120List in the order AIR, SEA, ROAD, matching the typical template order.121122## 2. Indicative Module RFQ (EXW Only)123124An RFQ requests indicative pricing for medical modules without a confirmed125destination, so freight is excluded and the quote is EXW only.126127### API calls1281291. `GET /api/rfqs/<rfq_id>` — confirms the RFQ, customer ID, requested modules130 with `product_code` and `quantity` per module, and request type.1312. `GET /api/customers/<customer_id>` — confirms customer type (new NGO vs132 recurring), segment, and payment_profile.1333. For each module in the RFQ's `requested_modules`, call134 `GET /api/products/<product_code>` to get the product name, article number,135 unit price tier, lead time, and shelf life.1364. `GET /api/policies` — confirms module-level quoting policy137 (`POL-MODULE-GRANULARITY`), EXW-only scope for indicative quotes without138 destination (`POL-INDICATIVE-EXW`), quote validity (`POL-QUOTE-VALIDITY`),139 and payment terms for new clients (`POL-NEW-CLIENT-PAYMENT`).140141### Module-level quoting142143The RFQ narrative and the policy `POL-MODULE-GRANULARITY` both instruct quoting144at module level only, even when the API exposes `component_composition_distractors`145or product `components` arrays. Each RFQ module becomes one line item with the146module's product code, article number, quantity, and unit price.147148When a product has a single price tier covering all quantities (min_qty 1,149max_qty null), use that tier directly. Multiply quantity by unit price for the150line total.151152### Payment terms for new NGOs153154Check the customer's `payment_profile`. For `"NEW_CLIENT_REVIEW"` or similar,155apply `PREPAY_100` per the new-client policy. For recurring customers with156`NET_30_AFTER_PO`, use that.157158### Quote validity159160If the output template asks for `offer_validity_days`, use 30 calendar days161per `POL-QUOTE-VALIDITY` (standard catalog quote validity). For162`who_documentation_required`, set `true` when the RFQ involves medical modules163for an NGO — this is the safe default for humanitarian medical supply.164165- `freight_excluded` is always `true` for this workflow.166167## 3. Engagement & Milestone Reconciliation168169A won opportunity has milestone phases with associated invoices, payments,170revenue journals, events, and vouchers. Reconcile everything and produce171follow-up task instructions.172173### API calls1741751. `GET /api/opportunities/<opportunity_id>` — confirms stage, won amount,176 phases with phase IDs and amounts, contact, customer ID, and any notes.1772. `GET /api/customers/<customer_id>` — confirms customer name and details.1783. `GET /api/invoices` — filter client-side by `opportunity_id` to match the179 opportunity's phases to their invoices.1804. `GET /api/payments` — filter by `opportunity_id` to see which invoices181 have been paid.1825. `GET /api/revenue-journals` — filter by `opportunity_id` to see which183 completed paid milestones have revenue recognition entries.1846. `GET /api/events` — find events whose `opportunity_id` matches. Use the185 event's `primary_contact` and `voucher_code` details.1867. `GET /api/vouchers/<voucher_code>` — confirms voucher status, discount,187 max uses.1888. `GET /api/policies` — confirms revenue recognition rule189 (`POL-REVREC`), payment terms, and quote validity.190191### Cross-referencing logic192193For each phase in the opportunity:194195- Match the phase to its invoice via `invoice_id` on the phase record.196- Match the invoice to payments: if `paid_amount_usd >= amount_usd`, the197 milestone is PAID; if `paid_amount_usd > 0` but less than full, it is198 PARTIAL; otherwise UNPAID.199- Match to revenue journals: look for a journal entry whose `phase_id`200 matches and whose `status` is `"posted"`.201202**Revenue recognition status per milestone:**203204| Invoice paid? | Revenue journal exists? | Status |205|---|---|---|206| Yes | Yes | `RECOGNIZED` |207| Yes | No | `MISSING_REVENUE_JOURNAL` or `REQUIRED_MISSING` |208| No | N/A | `NOT_REQUIRED_UNPAID` |209210**Overall revenue recognition status:**211212- If every paid milestone has a revenue journal → `COMPLETE_FOR_PAID_MILESTONES`213- If any paid milestone lacks a journal → `MISSING_FOR_PAID_MILESTONES`214- If no milestones are paid → `NOT_REQUIRED`215216**Opportunity-to-phase matching:** sum all phase amounts and compare to217`won_amount_usd`. Set `opportunity_matches_milestones` or218`opportunity_matches_phase_total` to `true` when they are equal.219220**Outstanding balance:** sum `outstanding_amount_usd` (or amount unpaid) across221all invoices for the opportunity.222223### Follow-up task routing224225Produce exactly the tasks the data demands:226227**Collection tasks:**228- If any milestone is unpaid with a due date on or before the as-of date, it229 is overdue → action is `COLLECT_UNPAID_MILESTONE` or `SEND_COLLECTION_NOTICE`,230 owner queue is `COLLECTIONS` or `ACCOUNT_MANAGEMENT`.231- If unpaid but not yet due → action is `MONITOR_UNPAID_NOT_DUE`, owner queue232 is `ACCOUNT_MANAGEMENT`.233- If no unpaid milestones exist → `NO_COLLECTION_ACTION`.234235**Revenue recognition tasks:**236- If any paid milestone has `MISSING_REVENUE_JOURNAL` → action is237 `RECORD_REVENUE_MS2` (or the specific milestone), debit `DEFERRED_REVENUE`,238 credit `IMPLEMENTATION_SERVICES_REVENUE`, owner queue `ACCOUNTING`.239- If all paid milestones are recognized → `NO_ACCOUNTING_ACTION` or240 `VERIFY_REVENUE_ONLY`.241242**Event/invitation tasks:**243- If an event exists with status `scheduled` or `confirmed` and its244 voucher is active → action is `SEND_BRIEFING_INVITE` or245 `SEND_EVENT_INVITATION`, owner queue `ACCOUNT_MANAGEMENT`, contact246 from the event's `primary_contact` field.247- If the event is in the past or completed → `NO_INVITE_ACTION`.248249### Accounting action details250251When a revenue recognition journal is missing for a paid milestone, produce252the accounting action entry:253254- `action`: `RECORD_REVENUE_<milestone_id>` (e.g. `RECORD_REVENUE_MS2`)255- `milestone_id`: the specific milestone ID256- `amount`: the milestone amount257- `debit_account`: `DEFERRED_REVENUE`258- `credit_account`: `IMPLEMENTATION_SERVICES_REVENUE`259- `owner_queue`: `ACCOUNTING`260261This mirrors the standard pattern from the revenue recognition policy.262263## Error handling264265- If an API call returns an empty response or an error, verify the ID and266 retry once. If it still fails, leave the corresponding output field empty267 or at its null/zero default instead of guessing.268- If the prompt names an entity that does not exist in the API, return the269 template with empty fields and include a `_note` field explaining the270 missing record.271272## Reference files273274- [references/policy-rules.md](references/policy-rules.md) — Full list of275 MedBridge policy rules and how they apply per workflow.276- [references/reconciliation-patterns.md](references/reconciliation-patterns.md) —277 Detailed reconciliation decision tables for milestone, invoice, payment,278 and revenue journal cross-referencing.279- [references/field-mappings.md](references/field-mappings.md) — API field to280 template field mappings for each workflow's common template shapes.281282Read a reference when the data demands more detail than the workflow section283above covers. The policy rules reference is especially useful when a task284mentions an unfamiliar policy area.