Hold/Reserve Ticket Inventory

To prevent customers from losing access to inventory after making payment, use the hold/reservation endpoint to reserve tickets.

Important Note for All Integrations: You must create holds before completing ticket purchases. This is a critical step that prevents situations where customers complete payment but tickets/seats/rooms are no longer available. Holds temporarily reserve inventory for 3 minutes while your customer completes checkout, guaranteeing availability during the payment process.

---

Hold/Reserve Experience Tickets

Temporarily reserve experience tickets (concerts, shows, events, cinema movies) before a customer completes their purchase. This endpoint ensures ticket availability during checkout and prevents overselling.

When to use: Before purchasing any experience tickets - whether regular events or cinema movies.

Hold/Reserve Experience Inventory

---

Hold/Reserve Transport Tickets

Temporarily reserve bus tickets and seats before a customer completes their purchase. Supports both timed schedules (specific seats) and random schedules (general boarding slots).

When to use: Before purchasing transport tickets on any schedule type.

Key features:

• Timed schedules: Reserve specific seat numbers

• Random schedules: Reserve general passenger slots

• Single endpoint handles both schedule types

Hold/Reserve Transport Tickets

---

Hold/Reserve Hospitality Rooms

Temporarily reserve hotel rooms, resort accommodations, or apartment bookings before a customer completes their purchase. Holds ensure room availability for the specified check-in and check-out dates.

When to use: Before booking any hotel, resort, or apartment accommodation.

Key features:

• Reserve rooms for specific date ranges

• Supports multi-night stays

Hold/Reserve Hospitality Rooms

---

Release Hold Early

Manually release active holds before their automatic expiration. Use this endpoint when a customer abandons checkout, cancels their selection, or you need to free up inventory programmatically.

When to use:

• Customer removes items from cart

• Customer abandons checkout

• Session timeout or inactivity

• Customer explicitly cancels selection

Note: Holds automatically expire after 3 minutes, so manual release is optional. It's primarily useful for improving inventory availability and user experience.

Release a Hold/Reservation Early

---

How Holds Work

The Hold Lifecycle

1. Create Hold (POST /api/v1/merpi/validate)
   ↓
   Status: "active" - Inventory reserved for 3 minutes
   ↓
2a. Complete Purchase → Status: "converted" (Hold becomes booking)
2b. Manual Release → Status: "released" (Inventory freed)
2c. TTL Expires → Status: "expired" (Inventory freed automatically)

Key Concepts

Reservation IDs: When you create holds, you receive reservation_id values. These UUIDs are required when completing purchases - they prove you have reserved inventory.

Customer Ownership: Holds are tied to customer email/phone number. The same credentials used to create holds must be used when purchasing or releasing them.

Time-to-Live (TTL): All holds automatically expire after 3 minutes (configurable). This prevents inventory from being locked indefinitely.

Idempotency: Submitting identical hold parameters while an active hold exists returns the existing hold instead of creating a duplicate.

Batch Rollback: When creating multiple holds in one request, if any hold fails, all previously created holds in that request are automatically released. This ensures all-or-nothing consistency.