Automotive Marketplace Transaction Integrity Playbook

Design and review an automotive marketplace transaction path with explicit inventory authority, versioned pricing, safe reservation, idempotent external effects,...

trigger="An automotive marketplace must make vehicle availability, price, reservation, payment, fulfillment, and ownership transfer reliable across dealer systems, marketplace services, providers, and human operations." owner="The transaction-domain owner accountable for the state model, authority boundaries, external effects, reconciliation, operator controls, and acceptance evidence." participants={["Marketplace product", "Inventory and dealer integration", "Payments or finance", "Order and fulfillment", "Security", "Data and search", "Platform or SRE", "Support operations"]} prerequisites={[ "A bounded transaction journey, named market or cohort, and access to representative dealer, inventory, payment, order, and fulfillment evidence.", "Named authorities for vehicle availability, price approval, reservation, payment result, order state, and ownership or handover evidence.", "A controlled environment or pilot cohort where duplicate, delayed, stale, and unknown-outcome cases can be exercised safely." ]} outputs={[ "A versioned transaction state model and authority map.", "Contracts for dealer ingestion, search freshness, reservation, pricing, payment operations, fulfillment, and reconciliation.", "Failure tests, operator procedures, observability, and a discrepancy queue.", "A bounded release and acceptance packet for one production transaction path." ]} doneWhen={[ "The same vehicle cannot be validly sold through two marketplace transactions under the tested authority model.", "A retry cannot create an untracked duplicate payment, reservation, fulfillment, or communication effect.", "Unknown outcomes are reconciled from authoritative evidence and aged discrepancies have named owners.", "Support can explain and act on a disputed transaction without direct database edits or unsupported guesses." ]} />

Treat the transaction as a chain of authorities

An automotive marketplace does not own every fact in a vehicle transaction. A dealer may own the current sellable inventory. An inspection system may own condition evidence. A pricing workflow may own an approved offer. A payment provider owns the provider-side result. A logistics or dealer operation owns handover evidence. Government or partner processes may determine title transfer.

The marketplace must connect those authorities without collapsing them into one status field. “Sold” may mean a buyer paid, a dealer accepted, inventory was removed, the vehicle was handed over, or ownership transfer completed. Those are different facts with different evidence and recovery paths.

This playbook uses an illustrative industry pattern. It does not claim a particular client architecture or result. Apply it to the actual market, regulatory environment, payment model, dealer agreement, inventory source, and fulfillment process.

1. Bound one transaction journey

Choose one journey such as reserve a listed used vehicle, pay a booking amount, receive dealer confirmation, complete inspection or documentation, and record handover. State the buyer type, seller or dealer type, market, vehicle class, payment method, delivery model, and exceptional cases inside the pilot.

List adjacent capabilities that are out of scope, such as financing approval, insurance, registration transfer, trade-in valuation, home delivery, auction bidding, or cross-border transactions. Record how the selected journey interacts with them, but do not let every automotive capability enter the first transaction model.

Define success in business-invariant language:

one authoritative sellable state exists for a vehicle in the pilot boundary;
every reservation has an owner, version, purpose, and expiry;
a price accepted by the buyer can be traced to an authorized version and conditions;
every external money operation has a stable operation identity and provider evidence;
fulfillment cannot advance from a label alone when required evidence is missing;
every terminal discrepancy is owned and auditable;
privacy and authorization apply to buyer, dealer, operator, and integration access.

2. Name authority for every changing fact

Create an authority register. A system of record is not automatically authoritative for every decision. Authority may depend on lifecycle stage and contract.

| Fact | Candidate authority | Version or evidence | Failure question | | --- | --- | --- | --- | | Vehicle identity | VIN and approved source record | Source, normalization version, match decision | Are two records the same vehicle? | | Sellable availability | Inventory authority | Inventory version, state, source time | Is the listing stale or concurrently reserved elsewhere? | | Condition | Inspection authority | Inspection version, inspector, validity window | Has material condition changed since inspection? | | Price | Approved price or offer service | Amount, currency, conditions, expiry, approver | Can a stale client price be accepted? | | Reservation | Reservation service | Vehicle, buyer, version, expiry, conversion status | Can two requests hold the last unit? | | Payment | Payment operation plus provider | Operation ID, idempotency key, provider reference | Did a timeout occur before or after provider acceptance? | | Order | Marketplace order state machine | Transition version, actor, evidence | Which facts allow the order to advance? | | Handover | Fulfillment or dealer evidence | Named actor, time, checklist, receipt | Can handover be disputed or reversed? | | Title or ownership | Approved transfer evidence | Jurisdiction-specific reference | Is commercial completion different from legal transfer? |

Search, analytics, recommendations, customer profiles, and reporting are usually derived views. They may be fast and useful, but they should not authorize a reservation or payment without validating the current authoritative state.

3. Build a versioned vehicle identity and inventory contract

Dealer feeds can be delayed, incomplete, duplicated, or corrected. Normalize source records into a stable internal vehicle identity while preserving source evidence. Do not use a mutable dealer listing ID as the only vehicle identity.

The ingestion contract should include source organization, source record ID, received time, source event or snapshot version, VIN or approved alternate identifiers, listed attributes, availability, location, asking price, inspection reference, and validation result. Quarantine records that fail identity, required-field, ownership, or policy checks.

Decide how conflicts are handled. If two sources claim the same vehicle, do not silently merge based on a weak match. Record candidates, evidence, decision, and owner. If the feed is a snapshot, detect missing records and define whether absence means unavailable, deleted, or temporarily unknown.

Inventory authority should expose a compare-and-set or equivalent versioned reservation operation. The command includes vehicle ID, expected inventory version, buyer or session identity, purpose, requested expiry, and request identity. It either creates the reservation against that version or returns a conflict with the current state. This prevents two successful reservations from a read-then-write race.

4. Make search freshness explicit

Search and recommendations are projections. They trade freshness for query performance and ranking capability. Displaying a vehicle in search does not mean it can still be reserved.

Record source version and projection time for every searchable listing. Monitor ingestion delay, projection delay, stale-result rate, and reserve-after-search conflicts. Use those measures to set a freshness objective that reflects buyer consequence and source behavior.

At the point of a consequential action, revalidate authoritative availability, price, policy, and user permissions. Explain the conflict in product language. “This vehicle was just reserved” is better than a generic server error. Offer a safe refresh or alternative instead of repeating the command automatically.

If a market requires temporary offline dealer operation or delayed feeds, represent confidence and last-verified time. Do not imply real-time availability when the contract cannot support it.

5. Separate price display from price authority

A listing may show asking price, estimated total, negotiated offer, dealer-approved price, financing estimate, tax, fee, delivery cost, and add-on products. These numbers have different authorities and validity windows.

Create a price quote or approved-offer object with amount components, currency, market, vehicle, buyer eligibility when relevant, conditions, source versions, approver or rule version, created time, and expiry. The transaction references that version rather than copying an untraceable number from the interface.

At confirmation, verify the price object is valid for the current vehicle, buyer, market, and transaction state. If a required component changes, present a new version for explicit buyer acceptance. Never change the amount silently between review and payment.

Reconcile the final order and money movements to the accepted price components. Discounts, dealer contributions, marketplace fees, refunds, and adjustments need separate entries and business reasons. A single “total” field is not sufficient financial evidence.

6. Model reservation as a lifecycle

A reservation is a temporary allocation, not a Boolean. Use states such as requested, active, converting, converted, expired, released, and disputed. Each transition has preconditions, actor authority, atomic state change, effects, and recovery behavior.

Set expiry from product and operating evidence. A very short hold can create customer frustration during documentation or payment. A very long hold can suppress sellable inventory and create dealer conflict. Different transaction types may need different policies.

Expiration must be idempotent and race-safe. If payment confirmation and expiry occur concurrently, the state machine should allow only one valid transition from the expected version. The losing command receives the current state and follows a defined reconciliation path.

Do not release a reservation merely because a payment request timed out. The payment outcome may be unknown. Move the transaction into a reconciliation state and retain the hold for a bounded period or follow the market-specific risk policy.

7. Give every external effect a stable operation identity

Payments, refunds, dealer notifications, logistics bookings, document submissions, and customer messages can execute outside the marketplace transaction. A network timeout cannot tell the caller whether the provider performed the operation.

Before calling a provider, create a durable operation record with transaction ID, organization context, operation type, request fingerprint, provider account, idempotency key, attempt, expected amount or payload, and current state. Commit the local intent before sending the external request.

When the provider supports idempotency, use a stable key for the same logical operation. Stripe’s idempotent request guidance explains that retries using the same key can return the stored result rather than creating another operation. Provider behavior and retention windows differ, so preserve your own operation record and do not rely on the provider key as a permanent ledger.

For providers without suitable idempotency, add a deterministic merchant reference, query-before-repeat behavior, or a mediated adapter that can recognize duplicate intent. If no safe retry exists, route the unknown outcome to reconciliation rather than guessing.

8. Recover unknown payment outcomes

When a payment call times out, keep four facts separate: the buyer requested payment, the marketplace sent an operation, the response is unknown, and the provider may or may not have accepted it. Do not label the order paid or failed until evidence supports that decision.

The recovery worker queries the provider using the merchant reference or receives a signed provider event. It validates provider account, amount, currency, transaction relationship, event authenticity, and whether the event is newer than the recorded provider state. It then applies one idempotent transition and financial entry.

Webhook delivery can be delayed, duplicated, or reordered. Store provider event identity and processing result. Reprocessing the same event must not repeat a business effect. An older event must not regress a terminal state without a deliberate dispute or reversal transition.

Set an age limit for unresolved operations. When breached, create an operator case with the evidence already gathered, permitted actions, customer communication guidance, and escalation owner. The operator should never need to create a second charge just to discover the first result.

9. Keep the financial ledger distinct from order status

An order label is not a financial ledger. Record money movements as immutable or append-only entries linked to business reason and provider evidence. Examples include authorization, capture, booking amount, refund, fee, dealer payable, marketplace receivable, adjustment, and dispute.

For each entry, store amount, currency, type, transaction, related operation, provider references, effective time, recorded time, counterparty, and reconciliation status. Corrections create compensating entries rather than overwriting history.

Reconcile at a cadence appropriate to volume and risk. Compare the marketplace operation ledger, provider transaction data, settlement or balance records, orders, reservations, refunds, and dealer obligations. Detect missing records, duplicate references, amount differences, currency differences, unexpected state, and aged unknowns.

Assign every discrepancy a severity, age, owner, permitted actions, communication status, and resolution evidence. Track whether the queue shrinks through resolution or merely through suppression.

10. Make fulfillment evidence part of the state model

Fulfillment for a vehicle may include dealer confirmation, documentation, inspection confirmation, financing, insurance, registration, delivery or pickup, handover, and ownership transfer. Model only the steps relevant to the market, but give each required step an authority and evidence type.

An operator should not set “delivered” through a generic status control. Expose commands such as confirm document verification, schedule pickup, record handover, acknowledge delivery, or record transfer reference. Each command validates actor authority, expected order state, required evidence, and version.

Handle exceptions explicitly: buyer cancellation, dealer withdrawal, inspection disagreement, document failure, delayed financing, vehicle damage, failed delivery, refund, and dispute. Define which states are reversible, which require compensation, and which need a new transaction.

Customer communication should reflect known facts. “We are confirming the payment result” is more accurate than “payment failed” after a timeout. Provide support with the same evidence and language rules.

11. Protect object and function authorization

Marketplace APIs expose vehicles, offers, reservations, orders, documents, payments, dealer operations, and support functions. Validate access to the specific object and action on every request. A user being authenticated does not authorize access to another buyer’s order or another dealer’s inventory.

The OWASP API Security Top 10 highlights broken object-level authorization, broken function-level authorization, unrestricted resource consumption, sensitive business flows, and unsafe consumption of APIs among the major risks. Translate those categories into transaction tests.

Test buyer, dealer, partner, support, finance, and service identities. Include negative cases for predictable IDs, organization switching, export, document access, bulk actions, administrative routes, webhook endpoints, and background workers. Support access should be named, time-bound, purpose-bound, and audited.

Limit automated access to search, reservations, pricing, and purchase flows based on business consequence, not only infrastructure capacity. Rate limiting alone may not stop distributed abuse. Use inventory, identity, behavioral, and transaction controls together.

12. Build an operator discrepancy console

Operators need a case view that joins the transaction timeline without giving them unrestricted mutation power. Show vehicle and inventory versions, reservation, accepted price, payment operations, provider evidence, ledger entries, order transitions, fulfillment evidence, communications, and related incidents.

Provide scoped actions with preconditions and confirmation. Examples include query provider, resend an eligible notification, extend a reservation within policy, approve a bounded refund, release a reservation after reconciliation, or escalate to finance. Record actor, reason, prior state, command, result, and related evidence.

Never provide a generic “set status” operation. If a real exception requires a new action, model it as a command with authority and audit rather than normalizing direct database edits.

The console should make uncertainty visible. Use states such as awaiting provider evidence, inventory conflict, document review, finance reconciliation, or customer response. Aged cases need a service objective and escalation path.

13. Instrument the end-to-end journey

Carry correlation, transaction, organization, actor, vehicle, reservation, operation, and order identity through requests, events, jobs, provider adapters, and logs according to privacy policy. Avoid sensitive document or payment data in unrestricted telemetry.

OpenTelemetry describes traces, metrics, logs, and baggage as complementary signals for understanding system activity. Its signals guidance is a useful basis, but the marketplace still needs domain events and reconciliation records that explain business outcomes.

Monitor:

search projection freshness and reserve-after-search conflict;
reservation creation, expiry, conversion, and contention;
payment operation success, unknown-outcome age, duplicate suppression, and reconciliation;
order transition rejection and exceptional-state age;
fulfillment delay and evidence completeness;
financial discrepancy count, value, age, and owner;
authorization denial and suspicious business-flow use;
provider latency, errors, event delay, and schema change;
operator intervention volume and reason.

Connect alerts to a named action. A dashboard without an operating response is not a control.

14. Run failure and concurrency tests

Test real conflict and partial-failure sequences, not only happy-path load.

| Test | Required result | | --- | --- | | Two buyers reserve the same vehicle version | One active reservation or an explicitly supported alternative; the other receives a conflict | | Dealer feed marks a reserved vehicle unavailable | A governed conflict path preserves evidence and assigns an owner | | Price expires during confirmation | The old version is rejected and a new version requires explicit acceptance | | Payment provider accepts but response times out | The transaction enters unknown outcome; no unguarded second charge occurs | | Duplicate or older provider event arrives | No duplicate financial effect and no invalid state regression | | Fulfillment command repeats after a worker crash | The effect is idempotent or the duplicate is detected and reconciled | | Buyer requests another buyer’s order | Access is denied and evidence is retained | | Dealer operator acts on another dealer’s inventory | Object and organization authorization deny the command | | Release rolls back with transactions in flight | Compatible workers and schemas preserve one executor and understandable state | | Reconciliation source is unavailable | Discrepancies remain visible; the system does not infer success |

Use representative hot vehicles, shared provider limits, delayed events, stale feed versions, and operator actions. Preserve the timeline for review.

15. Release one bounded market and cohort

Define pilot dealers, buyer cohort, vehicle types, payment methods, support coverage, transaction limits, and stop conditions. Confirm the old and new paths cannot both execute the same operation without duplicate protection.

Before exposure, verify the authority map, state transitions, idempotency, webhook security, authorization, reconciliation, operator procedures, dashboards, alerts, rollback, in-flight handling, customer communication, and accountable approval.

During the pilot, review transaction completion, unknown outcomes, inventory conflicts, payment discrepancies, fulfillment exceptions, support contacts, latency, cost, and security signals. Sample individual timelines, not only aggregates.

Expand only after terminal outcomes reconcile and operators can handle realistic exceptions. Rollback should stop new admission to the affected path while preserving already executed external effects for reconciliation. Do not delete or rewrite history to make the release appear clean.

Acceptance checklist

'The journey, market, cohort, payment model, and exclusions are bounded.', 'Vehicle, inventory, inspection, price, reservation, payment, order, fulfillment, and transfer authorities are named.', 'Search freshness and consequential revalidation are measurable.', 'Reservation and order transitions are versioned, authorized, and race-safe.', 'Every external effect has a durable operation identity and retry policy.', 'Unknown payment and provider outcomes enter reconciliation rather than an unguarded retry.', 'Financial entries preserve provider evidence and corrections are auditable.', 'Buyer, dealer, operator, integration, and support authorization have negative tests.', 'Operators have scoped commands and cannot use a generic status override.', 'Failure, concurrency, rollback, and recovery tests pass for the pilot boundary.', 'Every discrepancy has severity, age, owner, permitted action, and resolution evidence.', 'Expansion depends on reconciled business invariants, not only successful interface demos.', ]} />

Limits and cases where this playbook does not apply directly

This playbook does not define local tax, financing, insurance, consumer-protection, dealer, title, registration, identity-verification, or payment regulation. It does not prescribe one payment provider, database, cloud, search engine, or event platform. Those choices require market-specific review.

A classifieds marketplace that only introduces buyer and seller has a different transaction authority boundary from a marketplace that accepts payment, guarantees inventory, finances the vehicle, or owns fulfillment. Do not adopt states and controls for responsibilities the business does not hold.

The architecture also changes for auctions, fleet transactions, new vehicles with configurable inventory, cross-border imports, or offline-first dealer operations. Keep the invariant method, but rewrite the authority map, state machine, evidence, and recovery paths.