Sharetribe Flex Custom Transaction Process: State Machines, Multi-Day Bookings & Escrow Workflows

The short answer: What is a custom transaction process in Sharetribe Flex?

A Sharetribe Flex transaction process is a deterministic state machine that controls how a listing progresses from inquiry to payment authorization, operator approval, escrow holding, fulfillment, and payout. Customizing this process lets you add intermediary states (such as ID verification gates, dispute arbitrations, or refundable damage deposits) and specify which actor (customer, provider, or privileged operator backend) can execute each state transition.

Why Default Sharetribe Booking Workflows Break in Production

When building rental, B2B, or high-touch service marketplaces, founders quickly discover that Sharetribe's default "instant booking" and "booking with review" templates make three critical architectural assumptions:

• Single payment event: The entire booking amount (listing price + platform fee) is charged and immediately routed to the provider's Stripe Connect account upon completion.
• Binary dispute model: Either the transaction succeeds 100% or fails 100%. Partial refunds, retained deposits, and late return fees cannot be executed natively within standard client-side transitions.
• Fixed actor permissions: Only the customer or provider can initiate transitions, preventing external verification systems (like Stripe Identity or Jumio KYC) from gating the booking.

During our engineering of Tutti Vacation's custom vacation rental platform and RentCaar's peer-to-peer vehicle rental marketplace, we had to dismantle these assumptions by building custom multi-stage transaction graphs.

Deconstructing the Sharetribe Flex State Machine Architecture

Every Flex process file consists of three core primitives: States, Transitions, and Actions.

Architecting Two-Stage Security Deposits and Escrow Workflows

The most common requirement for equipment and vehicle rental platforms is holding a refundable security deposit (e.g., $500) alongside the rental fee (e.g., $150/day).

Because Stripe authorization holds expire after 7 days (or 30 days for card-present terminal payments), you cannot simply authorize a single PaymentIntent for a 14-day booking. Here is the production architecture we recommend:

1. Split Authorization via Privileged Microservice

Instead of routing payments directly through the client-side Flex template, the checkout form invokes a custom server endpoint (built on Node.js or Ruby on Rails). The backend creates two separate Stripe objects:

• Primary PaymentIntent: Charged with capture_method: automatic or captured immediately upon provider acceptance. Uses Destination Charges with an application_fee_amount. You can calculate optimal marketplace margins using our Marketplace Fee & Commission Calculator.
• Deposit PaymentIntent (or SetupIntent): Created with capture_method: manual. The customer's card is authorized 24 hours prior to handover. If no damage is reported within 72 hours post-rental, the authorization is automatically canceled via webhook.

2. Privileged Operator Transitions

To prevent malicious buyers or sellers from manipulating transaction states, sensitive actions (such as releasing escrow or executing a damage penalty) must be marked as :actor.role/operator in the Flex transaction process:

{
  "name": "transition/claim-damage-deposit",
  "actor": ":actor.role/operator",
  "from": "state/inspection-pending",
  "to": "state/dispute-under-review",
  "actions": [
    {
      "name": "action/calculate-custom-penalty",
      "config": { "max_claim_percentage": 100 }
    }
  ]
}

Because this transition requires the Flex-Integration-Key, it can only be invoked by your secure backend application after photos and evidence are verified. Read our in-depth analysis on preventing payment bugs in our guide on Stripe Connect marketplace mistakes and production fixes.

Comparison: Default Flex Process vs Custom State Machine vs Custom Rails Engine

Real-World Implementation: Handling Availability & Conflict Resolution

In high-velocity booking marketplaces, two users frequently attempt to book the exact same calendar slots concurrently. Sharetribe Flex handles seat availability through Time Slot Reservations.

When a customer initiates transition/request-payment, Flex locks the calendar unit atomically. However, if your transaction includes an external approval step (such as manual provider confirmation within 24 hours), you must configure a time-to-live (TTL) expiration transition:

• Auto-expire trigger: If the provider fails to respond within 24 hours, the state machine automatically fires transition/expire-request.
• Stripe release: The un-captured PaymentIntent authorization is released immediately, avoiding unnecessary merchant interchange fees and buyer credit holds.
• Availability unlock: The blocked calendar dates are returned to the open pool instantly.

For detailed instructions on integrating custom React frontends with these endpoints, review our comprehensive pillar guide on how to build a custom Sharetribe Flex marketplace with Stripe Connect.

When Should You Migrate Off Sharetribe Flex State Machines?

While Sharetribe Flex is exceptionally flexible for 90% of marketplace concepts, we advise clients to evaluate a dedicated Rails or Node.js backend when they encounter these three hard boundaries:

1. Multi-vendor cart checkouts: Flex transactions are strictly 1-to-1 (one customer, one listing/provider). If a buyer needs to purchase from three vendors in a single checkout, you must either orchestrate three parallel Flex transactions or migrate to a custom Rails marketplace.
2. Subscription-based seller billing: If sellers pay a recurring monthly subscription rather than transaction commissions, managing this alongside transaction processes creates high operational overhead.
3. Complex regulatory escrow rules: Countries requiring dedicated banking escrow licenses (such as Singapore MAS or EU PSD2 compliance beyond standard Stripe Connect) often require custom ledger architectures.

Frequently Asked Questions

Can I modify an existing Sharetribe Flex transaction process after launching in production?
Yes, but existing active transactions will remain on the process version they started with. Flex allows versioned deployments (e.g., rental-process-v2). New transactions automatically use the updated version while ongoing bookings conclude safely on version 1.

How do I test custom Flex transaction processes locally before deploying?
You can use the Sharetribe Flex CLI (flex-cli) to validate process JSON definitions and push them to your Flex Test Environment. You can then trigger transitions through the Flex Integration API using Postman or automated test suites.

What happens if a provider declines a booking after payment is preauthorized?
The state machine fires transition/decline, which executes action/stripe-cancel-payment-intent. The hold on the buyer's credit card is voided immediately without incurring Stripe transaction processing fees.

Can TechVinta help customize our Sharetribe Flex transaction workflows?
Yes. Our team specializes in designing custom state machines, building privileged Node.js/Rails microservices, integrating complex Stripe Connect multi-party payouts, and building custom React/React Native frontends. Explore our Sharetribe Flex development services.