# How to model event vendor marketplace for events AI Source: https://fragment.dev/solutions/event-vendor-marketplace ## The workflow this guide solves An organizer accepts a vendor service booked through a platform. Reserve confirmed customer funds, then split the approved service amount between the provider payable and platform income. Fragment tracks balances and payout reservations; your application authorizes the allocation and the payment provider executes transfers. | System | Responsibility | | --- | --- | | Your application | Approve the business event, amount, and recipient. | | Fragment ledger | Record entries, enforce configured balance conditions, and track balances. | | Payment provider | Execute the transfer and report its outcome. | Food safety, venue rules and supplier eligibility are external. ## Define the source of truth before posting Store the event vendor booking, its approval, and supporting evidence in your application. Bind the record to its source, tenant, and recipient. Preserve the approved amount, record version, and payment status. Give each intended financial effect an immutable operation key and payload fingerprint. A ledger entry records an authorized financial movement. It does not execute an external payment or atomically commit your application database. Use opaque account identifiers and bind them server-side. Fixture identifiers are examples; a balance condition does not authorize a caller. ## Decide whether this ledger model fits Use this model to allocate funded customer balances between a provider payable and platform income, with reserved payouts and refunds. If application records and balances must share one database transaction, consider [the Postgres integration trade-off](/blog/fragment-vs-postgres). A provider who has already been paid cannot be refunded through an unfunded payable reversal. Paid-out clawbacks, chargebacks, processing fees and tax require separately reviewed extensions. ## Map the business states to money buckets The money path is: confirmed customer funds → available → case hold → provider payable plus platform fee → payout pending → confirmed payout; approved customer credits and refunds follow their own reserved path. Fund the customer balance from confirmed money. Reserve the accepted case amount. On authoritative service acceptance, split it between the provider payable and platform fee. An approved unpaid credit reverses explicitly identified provider and fee portions. Reserve a provider payout or customer refund before requesting its external effect. The schema declares the following leaf accounts. `:` denotes an instance of a template account; exact posting paths and parameter names are in the downloaded JSON. - `assets/confirmed-cash` - `liabilities/sources:/available` - `liabilities/sources:/cases:/held` - `liabilities/sources:/refunds:/pending` - `liabilities/payees:/cases:/approved` - `liabilities/payees:/cases:/payouts:/pending` - `income/cases:` All amounts in this example are USD cents encoded as integer strings. The figures below are illustrative test values, not proposed prices, compensation amounts or commercial terms. Token usage, service quantities and exchange rates are outside this example. ## Inspect the allowed entry types ### `event_vendor_marketplace_fund` Record a confirmed incoming payment; does not execute a payment ### `event_vendor_marketplace_reserve` Reserve customer prepayment for an authorized case ### `event_vendor_marketplace_release` Release an unused case hold to available customer funds ### `event_vendor_marketplace_complete` Split an accepted service amount between payee obligation and platform fee ### `event_vendor_marketplace_credit_service` Undo an approved unpaid service allocation, with explicit fee credit ### `event_vendor_marketplace_reserve_refund` Reserve a customer refund before calling the payment provider ### `event_vendor_marketplace_refund_settled` Record a refund only after the payment provider confirms it settled ### `event_vendor_marketplace_refund_failed` Release the refund reservation only after definitive failure ### `event_vendor_marketplace_reserve_payout` Reserve an approved payable before calling the payout provider ### `event_vendor_marketplace_payout_settled` Record confirmed external payout settlement ### `event_vendor_marketplace_payout_failed` Release reservation only after definitive external payout failure The case hold caps allocations; the provider approved balance and per-case fee balance cap credits independently. The application must enforce zero ≤ fee ≤ gross before posting. Payouts and refunds each consume their own pending reservation. The schema uses strong total-balance updates and postconditions on the relevant unlinked accounts, following the [consistency guide](https://fragment.dev/guides/configure-consistency). It does not impose a complete business state machine or authorize callers. Here is the actual `event_vendor_marketplace_reserve` entry definition from this schema: ```json { "type": "event_vendor_marketplace_reserve", "description": "Reserve customer prepayment for an authorized case", "lines": [ { "key": "line_1", "account": { "path": "liabilities/sources:{{source_id}}/available" }, "amount": "-{{amount}}" }, { "key": "line_2", "account": { "path": "liabilities/sources:{{source_id}}/cases:{{case_id}}/held" }, "amount": "{{amount}}" } ], "conditions": [ { "account": { "path": "liabilities/sources:{{source_id}}/available" }, "postcondition": { "totalBalance": { "gte": "0" } } } ] } ``` ## Walk through the expected balances Start with a fresh empty test ledger. Read the steps in order. The replay step deliberately repeats the funding operation key and payload; it must leave balances unchanged. Every rejected operation must also leave all balances unchanged. ### Step 1: fund [Link to this step](https://fragment.dev/solutions/event-vendor-marketplace#step-1-fund) Amount parameters, in cents: amount=1000. Expected outcome: `posted`. Expected result: The confirmed cash balance increases from 0 to 1,000 USD cents. The available funds balance increases from 0 to 1,000 USD cents. Entry: `event_vendor_marketplace_fund`. Posted changes (USD cents): - `assets/confirmed-cash`: +1000 - `liabilities/sources:1/available`: +1000 Balances after this step (USD cents): - `assets/confirmed-cash`: 1000 - `liabilities/sources:1/available`: 1000 ### Step 2: fund [Link to this step](https://fragment.dev/solutions/event-vendor-marketplace#step-2-fund) Amount parameters, in cents: amount=1000. Expected outcome: `replay`. Expected result: This retry reuses the original operation key and payload. No new entry is posted, so all balances stay unchanged. Entry: `event_vendor_marketplace_fund`. Posted changes (USD cents): No new entry posted. Balances unchanged. Balances after this step (USD cents): - `assets/confirmed-cash`: 1000 - `liabilities/sources:1/available`: 1000 ### Step 3: reserve [Link to this step](https://fragment.dev/solutions/event-vendor-marketplace#step-3-reserve) Amount parameters, in cents: amount=700. Expected outcome: `posted`. Expected result: The available funds balance decreases from 1,000 to 300 USD cents. The held funds balance increases from 0 to 700 USD cents. Entry: `event_vendor_marketplace_reserve`. Posted changes (USD cents): - `liabilities/sources:1/available`: -700 - `liabilities/sources:1/cases:1/held`: +700 Balances after this step (USD cents): - `liabilities/sources:1/available`: 300 - `liabilities/sources:1/cases:1/held`: 700 ### Step 4: reserve [Link to this step](https://fragment.dev/solutions/event-vendor-marketplace#step-4-reserve) Amount parameters, in cents: amount=400. Expected outcome: `condition_rejected`. Expected result: The ledger rejects this entry because a balance condition is not met. No balances change. Entry: `event_vendor_marketplace_reserve`. Posted changes (USD cents): No new entry posted. Balances unchanged. Balances after this step (USD cents): - `liabilities/sources:1/available`: 300 - `liabilities/sources:1/cases:1/held`: 700 ### Step 5: complete [Link to this step](https://fragment.dev/solutions/event-vendor-marketplace#step-5-complete) Amount parameters, in cents: fee=100, amount=500. Expected outcome: `posted`. Expected result: The held funds balance decreases from 700 to 200 USD cents. The approved payables balance increases from 0 to 400 USD cents. The income balance increases from 0 to 100 USD cents. Entry: `event_vendor_marketplace_complete`. Posted changes (USD cents): - `liabilities/sources:1/cases:1/held`: -500 - `liabilities/payees:1/cases:1/approved`: +400 - `income/cases:1`: +100 Balances after this step (USD cents): - `liabilities/sources:1/cases:1/held`: 200 - `liabilities/payees:1/cases:1/approved`: 400 - `income/cases:1`: 100 ### Step 6: complete [Link to this step](https://fragment.dev/solutions/event-vendor-marketplace#step-6-complete) Amount parameters, in cents: fee=20, amount=201. Expected outcome: `condition_rejected`. Expected result: The ledger rejects this entry because a balance condition is not met. No balances change. Entry: `event_vendor_marketplace_complete`. Posted changes (USD cents): No new entry posted. Balances unchanged. ### Step 7: complete [Link to this step](https://fragment.dev/solutions/event-vendor-marketplace#step-7-complete) Amount parameters, in cents: fee=11, amount=10. Expected outcome: `input_rejected`. Expected result: The application rejects these parameters before posting an entry. No balances change. Entry: `event_vendor_marketplace_complete`. Posted changes (USD cents): No new entry posted. Balances unchanged. ### Step 8: credit_service [Link to this step](https://fragment.dev/solutions/event-vendor-marketplace#step-8-credit_service) Amount parameters, in cents: payee_credit=80, fee_credit=20. Expected outcome: `posted`. Expected result: The approved payables balance decreases from 400 to 320 USD cents. The income balance decreases from 100 to 80 USD cents. The available funds balance increases from 300 to 400 USD cents. Entry: `event_vendor_marketplace_credit_service`. Posted changes (USD cents): - `liabilities/payees:1/cases:1/approved`: -80 - `income/cases:1`: -20 - `liabilities/sources:1/available`: +100 Balances after this step (USD cents): - `liabilities/payees:1/cases:1/approved`: 320 - `income/cases:1`: 80 - `liabilities/sources:1/available`: 400 ### Step 9: credit_service [Link to this step](https://fragment.dev/solutions/event-vendor-marketplace#step-9-credit_service) Amount parameters, in cents: payee_credit=321, fee_credit=0. Expected outcome: `condition_rejected`. Expected result: The ledger rejects this entry because a balance condition is not met. No balances change. Entry: `event_vendor_marketplace_credit_service`. Posted changes (USD cents): No new entry posted. Balances unchanged. ### Step 10: credit_service [Link to this step](https://fragment.dev/solutions/event-vendor-marketplace#step-10-credit_service) Amount parameters, in cents: payee_credit=0, fee_credit=81. Expected outcome: `condition_rejected`. Expected result: The ledger rejects this entry because a balance condition is not met. No balances change. Entry: `event_vendor_marketplace_credit_service`. Posted changes (USD cents): No new entry posted. Balances unchanged. ### Step 11: release [Link to this step](https://fragment.dev/solutions/event-vendor-marketplace#step-11-release) Amount parameters, in cents: amount=200. Expected outcome: `posted`. Expected result: The held funds balance decreases from 200 to 0 USD cents. The available funds balance increases from 400 to 600 USD cents. Entry: `event_vendor_marketplace_release`. Posted changes (USD cents): - `liabilities/sources:1/cases:1/held`: -200 - `liabilities/sources:1/available`: +200 Balances after this step (USD cents): - `liabilities/sources:1/cases:1/held`: 0 - `liabilities/sources:1/available`: 600 ### Step 12: release [Link to this step](https://fragment.dev/solutions/event-vendor-marketplace#step-12-release) Amount parameters, in cents: amount=1. Expected outcome: `condition_rejected`. Expected result: The ledger rejects this entry because a balance condition is not met. No balances change. Entry: `event_vendor_marketplace_release`. Posted changes (USD cents): No new entry posted. Balances unchanged. ### Step 13: reserve_refund [Link to this step](https://fragment.dev/solutions/event-vendor-marketplace#step-13-reserve_refund) Amount parameters, in cents: amount=200. Expected outcome: `posted`. Expected result: The available funds balance decreases from 600 to 400 USD cents. The pending refunds balance increases from 0 to 200 USD cents. Entry: `event_vendor_marketplace_reserve_refund`. Posted changes (USD cents): - `liabilities/sources:1/available`: -200 - `liabilities/sources:1/refunds:1/pending`: +200 Balances after this step (USD cents): - `liabilities/sources:1/available`: 400 - `liabilities/sources:1/refunds:1/pending`: 200 ### Step 14: refund_failed [Link to this step](https://fragment.dev/solutions/event-vendor-marketplace#step-14-refund_failed) Amount parameters, in cents: amount=50. Expected outcome: `posted`. Expected result: The available funds balance increases from 400 to 450 USD cents. The pending refunds balance decreases from 200 to 150 USD cents. Entry: `event_vendor_marketplace_refund_failed`. Posted changes (USD cents): - `liabilities/sources:1/available`: +50 - `liabilities/sources:1/refunds:1/pending`: -50 Balances after this step (USD cents): - `liabilities/sources:1/available`: 450 - `liabilities/sources:1/refunds:1/pending`: 150 ### Step 15: refund_settled [Link to this step](https://fragment.dev/solutions/event-vendor-marketplace#step-15-refund_settled) Amount parameters, in cents: amount=150. Expected outcome: `posted`. Expected result: The pending refunds balance decreases from 150 to 0 USD cents. The confirmed cash balance decreases from 1,000 to 850 USD cents. Entry: `event_vendor_marketplace_refund_settled`. Posted changes (USD cents): - `liabilities/sources:1/refunds:1/pending`: -150 - `assets/confirmed-cash`: -150 Balances after this step (USD cents): - `liabilities/sources:1/refunds:1/pending`: 0 - `assets/confirmed-cash`: 850 ### Step 16: refund_settled [Link to this step](https://fragment.dev/solutions/event-vendor-marketplace#step-16-refund_settled) Amount parameters, in cents: amount=1. Expected outcome: `condition_rejected`. Expected result: The ledger rejects this entry because a balance condition is not met. No balances change. Entry: `event_vendor_marketplace_refund_settled`. Posted changes (USD cents): No new entry posted. Balances unchanged. ### Step 17: reserve [Link to this step](https://fragment.dev/solutions/event-vendor-marketplace#step-17-reserve) Amount parameters, in cents: amount=0. Expected outcome: `input_rejected`. Expected result: The application rejects these parameters before posting an entry. No balances change. Entry: `event_vendor_marketplace_reserve`. Posted changes (USD cents): No new entry posted. Balances unchanged. ### Step 18: reserve_payout [Link to this step](https://fragment.dev/solutions/event-vendor-marketplace#step-18-reserve_payout) Amount parameters, in cents: amount=320. Expected outcome: `posted`. Expected result: The approved payables balance decreases from 320 to 0 USD cents. The pending payouts balance increases from 0 to 320 USD cents. Entry: `event_vendor_marketplace_reserve_payout`. Posted changes (USD cents): - `liabilities/payees:1/cases:1/approved`: -320 - `liabilities/payees:1/cases:1/payouts:1/pending`: +320 Balances after this step (USD cents): - `liabilities/payees:1/cases:1/approved`: 0 - `liabilities/payees:1/cases:1/payouts:1/pending`: 320 ### Step 19: payout_failed [Link to this step](https://fragment.dev/solutions/event-vendor-marketplace#step-19-payout_failed) Amount parameters, in cents: amount=20. Expected outcome: `posted`. Expected result: The approved payables balance increases from 0 to 20 USD cents. The pending payouts balance decreases from 320 to 300 USD cents. Entry: `event_vendor_marketplace_payout_failed`. Posted changes (USD cents): - `liabilities/payees:1/cases:1/approved`: +20 - `liabilities/payees:1/cases:1/payouts:1/pending`: -20 Balances after this step (USD cents): - `liabilities/payees:1/cases:1/approved`: 20 - `liabilities/payees:1/cases:1/payouts:1/pending`: 300 ### Step 20: payout_settled [Link to this step](https://fragment.dev/solutions/event-vendor-marketplace#step-20-payout_settled) Amount parameters, in cents: amount=300. Expected outcome: `posted`. Expected result: The confirmed cash balance decreases from 850 to 550 USD cents. The pending payouts balance decreases from 300 to 0 USD cents. Entry: `event_vendor_marketplace_payout_settled`. Posted changes (USD cents): - `assets/confirmed-cash`: -300 - `liabilities/payees:1/cases:1/payouts:1/pending`: -300 Balances after this step (USD cents): - `assets/confirmed-cash`: 550 - `liabilities/payees:1/cases:1/payouts:1/pending`: 0 - `liabilities/payees:1/cases:1/approved`: 20 ### Step 21: credit_service [Link to this step](https://fragment.dev/solutions/event-vendor-marketplace#step-21-credit_service) Amount parameters, in cents: payee_credit=21, fee_credit=0. Expected outcome: `condition_rejected`. Expected result: The ledger rejects this entry because a balance condition is not met. No balances change. Entry: `event_vendor_marketplace_credit_service`. Posted changes (USD cents): No new entry posted. Balances unchanged. ### Step 22: payout_settled [Link to this step](https://fragment.dev/solutions/event-vendor-marketplace#step-22-payout_settled) Amount parameters, in cents: amount=1. Expected outcome: `condition_rejected`. Expected result: The ledger rejects this entry because a balance condition is not met. No balances change. Entry: `event_vendor_marketplace_payout_settled`. Posted changes (USD cents): No new entry posted. Balances unchanged. The account paths above match [the scenario file](/examples/vertical-ai/events--event-vendor-marketplace/scenarios.json). A snapshot lists the balances checked at that point; it does not assert that all other balances are zero. The included schema scene contains the accepted entries; the separate fixture file contains replay and rejection cases too. Some fixtures divide a reserved outgoing amount into a definitively failed portion and a settled portion. Your application must represent those as separately identified external sub-operations with exact amounts. This is an illustrative recovery sequence, not a claim that a given payment API supports partial failure on one request. ## Validate the schema and integrate a tool Download [schema.json](/examples/vertical-ai/events--event-vendor-marketplace/schema.json) and [the application contract](/examples/vertical-ai/events--event-vendor-marketplace/application-contract.json). Use the [shared tool guide](/api-reference/ledger-cli-commands) for installation and current official references. From the directory containing your reviewed schema: ```bash fragment verify-schema --path schema.json --json fragment gen-graphql --path=schema.json --output=queries.graphql ``` Choose the official SDK for your application's language and generate the schema-specific client as documented. For MCP, connect the intended workspace and confirm the target project before editing, simulation or deployment. Tool names can vary across server versions; enumerate the connected server instead of assuming a universal tool list. After the confirmed funding step, this is an example variable object for the first business allocation: ```json { "ik": "replace-with-stable-business-operation-key", "entry": { "ledger": { "ik": "replace-with-confirmed-test-ledger" }, "type": "event_vendor_marketplace_reserve", "typeVersion": 1, "parameters": { "source_id": "1", "case_id": "1", "amount": "700" } } } ``` Use it with the [documented AddLedgerEntry mutation](/examples/vertical-ai/AddLedgerEntry.graphql). Replace the test-ledger and operation-key placeholders with confirmed values; the other identifiers and amounts must match your authorized test case. [The complete accepted request sequence](/examples/vertical-ai/events--event-vendor-marketplace/requests.json) is provided as review data, not as an automatic execution script. Handle returned error results as well as transport failures. ## Enforce the application-side input contract The schema's balancing and nonnegative postconditions do not reject every invalid signed input. Validate these rules before posting, using the downloaded contract as the exact reference: ### `event_vendor_marketplace_fund` positive integers: amount ### `event_vendor_marketplace_reserve` positive integers: amount ### `event_vendor_marketplace_release` positive integers: amount ### `event_vendor_marketplace_complete` positive integers: amount; nonnegative integers: fee; fee ≤ amount ### `event_vendor_marketplace_credit_service` nonnegative integers: payee_credit, fee_credit; sum(payee_credit, fee_credit) > 0 ### `event_vendor_marketplace_reserve_refund` positive integers: amount ### `event_vendor_marketplace_refund_settled` positive integers: amount ### `event_vendor_marketplace_refund_failed` positive integers: amount ### `event_vendor_marketplace_reserve_payout` positive integers: amount ### `event_vendor_marketplace_payout_settled` positive integers: amount ### `event_vendor_marketplace_payout_failed` positive integers: amount Authorize the exact source, case and recipient; check the current approval version; and reject a command that conflicts with a terminal domain outcome. A new approval revision is a new business decision. A duplicate delivery of the same revision is a retry, with the same operation identity. ## What happens if a payment fails or its outcome is unknown? Keep funds reserved while the payment outcome is unknown. Release only the amount confirmed as definitively failed; record settlement only after provider confirmation. For a timed-out ledger request, retry the same operation key and payload to avoid posting twice. 1. Persist an authorized command and an outbox record before requesting an effect. Keep its ledger key, payload fingerprint, case version and provider operation identity durable. 2. Reserve the relevant available amount before requesting an outgoing payment. If the ledger request times out, recover using the same operation key and payload; do not invent a second operation because the first response was lost. 3. Submit the provider action according to that provider's idempotency and retry rules. Keep its identifier bound to the exact pending reservation. This guide supplies no provider-specific retention guarantee. 4. If the provider outcome is unknown, leave the amount reserved and reconcile it. An elapsed timer is not proof of failure. A definitive failed sub-operation can release its own amount; a confirmed settlement can consume its own amount. 5. Deduplicate callbacks and reject mismatched or stale case/payee/amount associations. Keep terminal operation decisions immutable and post authorized adjustments separately. 6. Reconcile `assets/confirmed-cash` against the actual external records. These schemas use a manually modeled cash account. A [linked-account reconciliation integration](https://fragment.dev/guides/reconcile-payments) is an additional implementation step, with separate unlinked buckets for conditional authorization. ## Exercise the industry-specific edges - Change the agreed fee for the event vendor booking after allocation; authorize an explicit adjustment to the affected balances. - Cancel the event vendor booking while a provider payout is pending; resolve that payout before assuming the funds can be refunded. - Test the boundary for this particular workflow: food safety, venue rules and supplier eligibility are external. The application should route the decision to the appropriate domain system rather than treating the ledger balance as authority. - Submit two competing commands that individually fit the current balance but together exceed it. In a live test ledger, verify that accepted total allocation stays within the available amount and that rejected commands have no effect. - Crash after reservation but before your application stores the response. Recover the recorded operation instead of crediting or debiting the case twice. ## Acceptance before using this with real money The originating schema passed the local Fragment parser and the earlier offline model fixtures. This written guide does not establish live API, concurrency, callback recovery or provider correctness. Before release, have a domain reviewer accept the stated boundaries, run the full fixture sequence in a fresh test ledger, compare actual balances with the expected snapshots, and test real retry/reorder/unknown-outcome recovery using controlled test operations. Also verify that one tenant cannot choose another tenant's source or case, that nonpositive or inconsistent amounts are rejected by the application, and that every posted movement has durable approval and payment evidence. Record the exact schema version and result traces. Publication and agent-discovery evaluation are separate from this integration acceptance. ## Related events workflows - [Venue reservation deposits](/solutions/event-payment-processing) - [Performer service payouts](/solutions/performer-service-payouts) - [Attendee compensation disbursements](/solutions/attendee-compensation-disbursements) - [Catering service prepayments](/solutions/catering-service-prepayments) ## Sources and companion files - [Quickstart: schema, SDK and API setup](https://fragment.dev/guides/quickstart) - [Posting entries: parameter strings and idempotency](https://fragment.dev/guides/post-ledger-entries) - [Consistency: strong balance conditions and linked-account restrictions](https://fragment.dev/guides/configure-consistency) - [Payment reconciliation](https://fragment.dev/guides/reconcile-payments) - [CLI reference](https://fragment.dev/api-reference/ledger-cli-commands) - [MCP reference](https://fragment.dev/api-reference/mcp) - [SDK reference](https://fragment.dev/api-reference/ledger-sdks) - [Schema](/examples/vertical-ai/events--event-vendor-marketplace/schema.json) - [Expected results](/examples/vertical-ai/events--event-vendor-marketplace/scenarios.json) - [Request variables](/examples/vertical-ai/events--event-vendor-marketplace/requests.json) - [Application contract](/examples/vertical-ai/events--event-vendor-marketplace/application-contract.json)