Introduction

Marketplace — ERP Integration Overview

ERP integrate with the Marketplace through a set of complementary surfaces. This guide is organized into self-contained areas, each with its own authentication, endpoints, and error handling:

• Product Sync — the Bridge API: catalog push/sync (publish, update, list products). Auth: X-Api-Key.
• Booking — the live booking surfaces: Stock Operations API (holds) and the Booking Webhook receiver. Auth: X-Api-Key + HMAC-SHA256.
• Stock Sync — the stock.updated webhook that keeps availability up-to-date. Auth: HMAC-SHA256 signing.
• Payment — the three selectable gateways (AceTours Pay, Stripe, FOMO Pay) and their auth/config.

Key principle: stock/availability is ERP-owned. The Bridge API seeds the first availability snapshot when a product is first published. After that, every allotment change must come through the stock.updated webhook — the Bridge availability field is ignored for products that already have availability records.

Getting Started

Environments

Credentials to request from EZCore

The webhook HMAC secret is covered under Stock Sync → Authentication.

Authentication

Product Sync · Bridge API

Every call to /api/v1/bridge/* authenticates with a single API-key header:

Rate limits: 60 write requests/min, 120 read requests/min per key.

Bridge API — Concepts

Lazy tenant provisioning

If the operator.slug in a publish request does not yet exist, the system auto-provisions a new tenant in pending status. The first publish still returns 201 Created. No pre-provisioning step is required.

Upsert by (operator, legacy_product_id)

The Bridge API is idempotent at the product level. If you POST a product with the same operator and legacy_product_id combination that already exists, the server performs an update instead of creating a duplicate:

• New product: HTTP 201 Created
• Existing product: HTTP 200 OK

Status values

Availability seeding — one-time only

The availability[] field in a Bridge publish request seeds availability only if the product has no existing availability records. On subsequent publishes (upserts) of the same product, availability[] is ignored. Ongoing stock management is done exclusively through the stock.updated webhook.

Publish a Product

Request body — top-level fields

Nested input objects

Sequence diagram

Request & Response

curl -X POST https://api-marketplace.ezbcloud.space/api/v1/bridge/products \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <bridge-service-key>" \
  -d '{
  "operator": {
    "id": "a1b2c3d4-0001-0001-0001-000000000001",
    "slug": "ace-tours",
    "name": "Ace Tours Pte Ltd"
  },
  "legacy_product_id": "BTM-001",
  "type": "tour_package",
  "name": "3D2N Batam Fun Package",
  "description": "All-inclusive Batam escape with your choice of ferry operator and hotel. Perfect for a quick weekend getaway from Singapore.",
  "destination": "Batam",
  "country_code": "ID",
  "destination_scope": "international",
  "images": [
    { "url": "https://picsum.photos/seed/batam1/800/600" },
    { "url": "https://picsum.photos/seed/batam2/800/600" }
  ],
  "inclusions": [
    "2 nights hotel accommodation",
    "Return ferry ticket",
    "Daily breakfast",
    "Batam city tour (half day)"
  ],
  "exclusions": [
    "Personal expenses",
    "Indonesia departure tax",
    "Optional tours"
  ],
  "physical_capacity": 50,
  "passenger_data_requirement": "full_details",
  "type_data": {
    "duration_nights": 2,
    "departure_point": "Singapore",
    "min_pax": 1,
    "max_pax": 10,
    "itinerary": [
      { "day": 1, "title": "Arrival in Batam", "description": "Ferry from Singapore HarbourFront. Check-in and leisure.", "meals": [], "accommodation": "Selected hotel" },
      { "day": 2, "title": "Batam City Tour", "description": "Half-day city tour covering Nagoya Hill and local seafood lunch. Afternoon at leisure.", "meals": ["breakfast"], "accommodation": "Selected hotel" },
      { "day": 3, "title": "Departure", "description": "Breakfast, check-out, return ferry to Singapore.", "meals": ["breakfast"], "accommodation": null }
    ],
    "component_groups": [
      {
        "code": "ferry",
        "label": "Ferry Operator",
        "is_required": true,
        "hold_unit": "per_pax",
        "options": [
          { "code": "batam-fast", "label": "Batam Fast", "is_default": true, "images": [{ "url": "https://picsum.photos/seed/ferry1/800/600" }], "product_id": null, "share_inventory": false, "use_product_pricing": false },
          { "code": "indo-falcon", "label": "Indo Falcon", "is_default": false, "images": [], "product_id": null, "share_inventory": false, "use_product_pricing": false }
        ]
      },
      {
        "code": "hotel",
        "label": "Hotel",
        "is_required": true,
        "hold_unit": "per_pax",
        "options": [
          { "code": "harris", "label": "Harris Resort Batam Center", "is_default": true, "images": [{ "url": "https://picsum.photos/seed/harris1/800/600" }], "product_id": null, "share_inventory": false, "use_product_pricing": false },
          { "code": "golden-view", "label": "Golden View Hotel", "is_default": false, "images": [], "product_id": null, "share_inventory": false, "use_product_pricing": false }
        ]
      }
    ]
  },
  "pricing": [
    { "pax_type": "adult", "amount": 299.00, "currency": "SGD" },
    { "pax_type": "child", "amount": 199.00, "currency": "SGD" },
    { "component_group": "ferry", "option_code": "batam-fast",  "pax_type": "adult", "amount": 0.01,  "currency": "SGD" },
    { "component_group": "ferry", "option_code": "batam-fast",  "pax_type": "child", "amount": 0.01,  "currency": "SGD" },
    { "component_group": "ferry", "option_code": "indo-falcon", "pax_type": "adult", "amount": 15.00, "currency": "SGD" },
    { "component_group": "ferry", "option_code": "indo-falcon", "pax_type": "child", "amount": 10.00, "currency": "SGD" },
    { "component_group": "hotel", "option_code": "harris",      "pax_type": "adult", "amount": 0.01,  "currency": "SGD" },
    { "component_group": "hotel", "option_code": "harris",      "pax_type": "child", "amount": 0.01,  "currency": "SGD" },
    { "component_group": "hotel", "option_code": "golden-view", "pax_type": "adult", "amount": 30.00, "currency": "SGD" },
    { "component_group": "hotel", "option_code": "golden-view", "pax_type": "child", "amount": 20.00, "currency": "SGD" }
  ],
  "availability": [
    {
      "start_date": "2026-07-01",
      "end_date": "2026-09-30",
      "total_allotment": 50,
      "component_allotments": [
        { "component_group": "ferry", "option_code": "batam-fast",  "total_allotment": 30 },
        { "component_group": "ferry", "option_code": "indo-falcon", "total_allotment": 20 },
        { "component_group": "hotel", "option_code": "harris",      "total_allotment": 25 },
        { "component_group": "hotel", "option_code": "golden-view", "total_allotment": 25 }
      ]
    },
    {
      "start_date": "2026-10-01",
      "end_date": "2026-12-31",
      "total_allotment": 40,
      "component_allotments": [
        { "component_group": "ferry", "option_code": "batam-fast",  "total_allotment": 20 },
        { "component_group": "ferry", "option_code": "indo-falcon", "total_allotment": 20 },
        { "component_group": "hotel", "option_code": "harris",      "total_allotment": 20 },
        { "component_group": "hotel", "option_code": "golden-view", "total_allotment": 20 }
      ]
    }
  ],
  "translations": [
    {
      "locale": "id",
      "name": "Paket Seru 3H2M Batam",
      "description": "Liburan singkat ke Batam, serba termasuk, dengan pilihan operator ferry dan hotel. Cocok untuk akhir pekan singkat dari Singapura.",
      "type_data": {
        "itinerary": [
          { "day": 1, "title": "Tiba di Batam", "description": "Ferry dari Singapore HarbourFront. Check-in dan waktu bebas." }
        ]
      }
    },
    {
      "locale": "zh",
      "name": "巴淡岛3天2晚欢乐套餐",
      "description": "全包式巴淡岛周末游，可自选渡轮公司和酒店，是新加坡出发的理想短途假期。",
      "type_data": {
        "itinerary": [
          { "day": 1, "title": "抵达巴淡岛", "description": "从新加坡港湾中心乘渡轮前往，办理入住手续后自由活动。" }
        ]
      }
    }
  ],
  "status": "published"
}'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "legacy_product_id": "BTM-001",
  "operator": { "id": "a1b2c3d4-0001-0001-0001-000000000001", "slug": "ace-tours", "name": "Ace Tours Pte Ltd" },
  "type": "tour_package",
  "name": "3D2N Batam Fun Package",
  "destination": "Batam",
  "country_code": "ID",
  "destination_scope": "international",
  "physical_capacity": 50,
  "status": "published",
  "b2c_visible": true,
  "translations": [
    {
      "locale": "id",
      "name": "Paket Seru 3H2M Batam",
      "description": "Liburan singkat ke Batam, serba termasuk, dengan pilihan operator ferry dan hotel. Cocok untuk akhir pekan singkat dari Singapura.",
      "type_data": {
        "itinerary": [
          { "day": 1, "title": "Tiba di Batam", "description": "Ferry dari Singapore HarbourFront. Check-in dan waktu bebas." }
        ]
      }
    },
    {
      "locale": "zh",
      "name": "巴淡岛3天2晚欢乐套餐",
      "description": "全包式巴淡岛周末游，可自选渡轮公司和酒店，是新加坡出发的理想短途假期。",
      "type_data": {
        "itinerary": [
          { "day": 1, "title": "抵达巴淡岛", "description": "从新加坡港湾中心乘渡轮前往，办理入住手续后自由活动。" }
        ]
      }
    }
  ],
  "created_at": "2026-07-01T10:00:00Z",
  "updated_at": "2026-07-01T10:00:00Z"
}

Update a Product

Partial update: only the fields you include are changed. Fields you omit keep their existing values.

Common update patterns

# Change status only
curl -X PUT https://api-marketplace.ezbcloud.space/api/v1/bridge/products/PKG-BALI-5D4N \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <key>" \
  -d '{ "status": "draft" }'

# Update pricing (entire block replaced)
curl -X PUT https://api-marketplace.ezbcloud.space/api/v1/bridge/products/PKG-BALI-5D4N \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <key>" \
  -d '{
    "pricing": [
      { "pax_type": "adult",  "amount": 949.00, "currency": "SGD" },
      { "pax_type": "child",  "amount": 749.00, "currency": "SGD" },
      { "pax_type": "infant", "amount": 99.00,  "currency": "SGD" }
    ]
  }'

Unpublish / Delist a Product

List Products (Sync)

Returns a paginated list of lightweight BridgeProductListItem objects (no type_data or images). Use for periodic reconciliation.

Query parameters

Response example

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "legacy_product_id": "PKG-BALI-5D4N",
      "type": "tour_package",
      "name": "Bali Cultural Journey 5D4N",
      "status": "published",
      "b2c_visible": true,
      "updated_at": "2026-07-01T10:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 1,
    "last_page": 1
  }
}

Product Types & type_data

Every product has a type field that selects one of six product types. Each type has a distinct type_data shape — a mismatch returns 422 Unprocessable Entity. The subsections below show the type_data fields and a full success-scenario publish example for each type.

Tour Package — type: "tour_package"

type_data fields

Pricing note for components: Base pricing is per pax_type. Component surcharges add extra rows keyed by component_group + option_code + pax_type. A surcharge of 0.01 means "no extra cost." Negative amounts are discounts.

Example — Bintan 3D2N with 3 component groups (success scenario)

This package lets the customer select a ferry, a resort, and a room type. Each group carries its own surcharge rows in pricing[] and per-option inventory in availability[].component_allotments[]. Default options are priced at 0.01 (no extra cost); upgrades add a surcharge.

{
  "operator": {
    "id": "a1b2c3d4-0011-0011-0011-000000000011",
    "slug": "sun-holidays",
    "name": "Sun Holidays Travel Pte Ltd"
  },
  "legacy_product_id": "PKG-BIN-3D2N-COMP",
  "type": "tour_package",
  "name": "Bintan Resort Escape 3D2N — Ferry, Hotel & Room Selection",
  "description": "Premium Bintan package with full component flexibility: choose your ferry, resort, and room type. Includes breakfast and a half-day island tour.",
  "destination": "Bintan",
  "country_code": "ID",
  "destination_scope": "international",
  "images": [
    { "url": "https://picsum.photos/seed/bin3d1/800/600" },
    { "url": "https://picsum.photos/seed/bin3d2/800/600" },
    { "url": "https://picsum.photos/seed/bin3d3/800/600" }
  ],
  "inclusions": [
    "2 nights resort (your choice)",
    "Return ferry (your choice)",
    "Daily breakfast",
    "Bintan island tour (half-day)"
  ],
  "exclusions": [
    "Watersports",
    "Dinner",
    "Indonesia departure tax"
  ],
  "physical_capacity": 60,
  "type_data": {
    "duration_nights": 2,
    "departure_point": "Singapore (Tanah Merah Ferry Terminal)",
    "min_pax": 2,
    "max_pax": 12,
    "itinerary": [
      { "day": 1, "title": "Arrival & Resort Check-in", "description": "Ferry from Tanah Merah. Resort check-in from 2 PM. Afternoon beach leisure.", "meals": [],           "accommodation": "Selected resort" },
      { "day": 2, "title": "Island Tour",               "description": "Morning half-day island discovery tour. Afternoon free at resort.",          "meals": ["breakfast"], "accommodation": "Selected resort" },
      { "day": 3, "title": "Departure",                 "description": "Breakfast. Check-out. Return ferry to Singapore.",                            "meals": ["breakfast"], "accommodation": null }
    ],
    "component_groups": [
      {
        "code": "ferry",
        "label": "Ferry",
        "is_required": true,
        "hold_unit": "per_pax",
        "options": [
          { "code": "bintan-resort-ferry", "label": "Bintan Resort Ferry", "is_default": true,  "images": [], "product_id": null, "share_inventory": false, "use_product_pricing": false },
          { "code": "majestic-fast",        "label": "Majestic Fast Ferry", "is_default": false, "images": [], "product_id": null, "share_inventory": false, "use_product_pricing": false }
        ]
      },
      {
        "code": "resort",
        "label": "Resort",
        "is_required": true,
        "hold_unit": "per_pax",
        "options": [
          { "code": "blag",    "label": "Bintan Lagoon Resort (5-star)",  "is_default": true,  "images": [{ "url": "https://picsum.photos/seed/blag/400/300" }], "product_id": null, "share_inventory": false, "use_product_pricing": false },
          { "code": "nirwana", "label": "Nirwana Gardens Resort (4-star)", "is_default": false, "images": [{ "url": "https://picsum.photos/seed/nirw/400/300" }], "product_id": null, "share_inventory": false, "use_product_pricing": false }
        ]
      },
      {
        "code": "room_type",
        "label": "Room Type",
        "is_required": true,
        "hold_unit": "per_booking",
        "options": [
          { "code": "garden", "label": "Garden View Room", "is_default": true,  "images": [], "product_id": null, "share_inventory": false, "use_product_pricing": false },
          { "code": "sea",    "label": "Sea View Room",    "is_default": false, "images": [], "product_id": null, "share_inventory": false, "use_product_pricing": false }
        ]
      }
    ]
  },
  "pricing": [
    { "pax_type": "adult", "amount": 349.00, "currency": "SGD" },
    { "pax_type": "child", "amount": 229.00, "currency": "SGD" },
    { "component_group": "ferry",     "option_code": "bintan-resort-ferry", "pax_type": "adult", "amount": 0.01,  "currency": "SGD" },
    { "component_group": "ferry",     "option_code": "bintan-resort-ferry", "pax_type": "child", "amount": 0.01,  "currency": "SGD" },
    { "component_group": "ferry",     "option_code": "majestic-fast",        "pax_type": "adult", "amount": 8.00,  "currency": "SGD" },
    { "component_group": "ferry",     "option_code": "majestic-fast",        "pax_type": "child", "amount": 5.00,  "currency": "SGD" },
    { "component_group": "resort",    "option_code": "blag",                 "pax_type": "adult", "amount": 50.00, "currency": "SGD" },
    { "component_group": "resort",    "option_code": "blag",                 "pax_type": "child", "amount": 50.00, "currency": "SGD" },
    { "component_group": "resort",    "option_code": "nirwana",              "pax_type": "adult", "amount": 0.01,  "currency": "SGD" },
    { "component_group": "resort",    "option_code": "nirwana",              "pax_type": "child", "amount": 0.01,  "currency": "SGD" },
    { "component_group": "room_type", "option_code": "garden",               "pax_type": "adult", "amount": 0.01,  "currency": "SGD" },
    { "component_group": "room_type", "option_code": "garden",               "pax_type": "child", "amount": 0.01,  "currency": "SGD" },
    { "component_group": "room_type", "option_code": "sea",                  "pax_type": "adult", "amount": 60.00, "currency": "SGD" },
    { "component_group": "room_type", "option_code": "sea",                  "pax_type": "child", "amount": 60.00, "currency": "SGD" }
  ],
  "availability": [
    {
      "start_date": "2026-07-01",
      "end_date": "2026-12-31",
      "total_allotment": 60,
      "component_allotments": [
        { "component_group": "ferry",     "option_code": "bintan-resort-ferry", "total_allotment": 40 },
        { "component_group": "ferry",     "option_code": "majestic-fast",        "total_allotment": 20 },
        { "component_group": "resort",    "option_code": "blag",                 "total_allotment": 30 },
        { "component_group": "resort",    "option_code": "nirwana",              "total_allotment": 30 },
        { "component_group": "room_type", "option_code": "garden",               "total_allotment": 40 },
        { "component_group": "room_type", "option_code": "sea",                  "total_allotment": 20 }
      ]
    }
  ],
  "status": "published"
}

Hotel — type: "hotel"

type_data fields

Top-level hotel extras (richer than current spec):

Pricing: keyed by variant_code (room code) × pax_type.
Availability: includes variant_allotments[] with { "variant_code": "std", "total_allotment": 50 }.

Example — HTL-02: 3-star, 2 room types, 1 addon (success scenario)

{
  "operator": {
    "id": "a1b2c3d4-0002-0002-0002-000000000002",
    "slug": "marina-hotels",
    "name": "Marina Hotels Group Pte Ltd"
  },
  "legacy_product_id": "HTL-MID-SGP-002",
  "type": "hotel",
  "name": "Orchard View Hotel",
  "description": "3-star hotel on Orchard Road. Modern rooms with city views, rooftop pool, 10-min walk to three MRT stations.",
  "destination": "Singapore",
  "country_code": "SG",
  "images": [
    { "url": "https://cdn.example.com/orchard-view1.jpg" },
    { "url": "https://cdn.example.com/orchard-view2.jpg" }
  ],
  "inclusions": ["Complimentary Wi-Fi", "Rooftop pool access", "Daily housekeeping"],
  "exclusions": ["Breakfast (available as add-on)", "Airport transfers", "Parking"],
  "physical_capacity": 80,
  "type_data": {
    "star_rating": 3,
    "check_in_time": "15:00",
    "check_out_time": "11:00",
    "amenities": ["wifi", "pool", "gym"],
    "room_types": [
      {
        "code": "std",
        "name": "Standard City Room",
        "description": "City view, queen bed, 24 sqm. En-suite with rain shower.",
        "max_guests": 2,
        "images": [{ "url": "https://cdn.example.com/orchard-std.jpg" }]
      },
      {
        "code": "dlx",
        "name": "Deluxe Orchard Room",
        "description": "Orchard Road view, king bed, 30 sqm. Separate soaking tub.",
        "max_guests": 2,
        "images": [{ "url": "https://cdn.example.com/orchard-dlx.jpg" }]
      }
    ]
  },
  "pricing": [
    { "variant_code": "std", "pax_type": "adult", "amount": 148.00, "currency": "SGD" },
    { "variant_code": "std", "pax_type": "child", "amount":   0.01, "currency": "SGD" },
    { "variant_code": "dlx", "pax_type": "adult", "amount": 188.00, "currency": "SGD" },
    { "variant_code": "dlx", "pax_type": "child", "amount":   0.01, "currency": "SGD" }
  ],
  "availability": [
    {
      "start_date": "2026-07-01",
      "end_date": "2026-12-31",
      "total_allotment": 80,
      "variant_allotments": [
        { "variant_code": "std", "total_allotment": 50 },
        { "variant_code": "dlx", "total_allotment": 30 }
      ]
    }
  ],
  "addons": [
    {
      "legacy_addon_id": "OVH-BRKFST",
      "name": "American Breakfast (per person)",
      "unit": "per_night",
      "price": 22.00,
      "currency": "SGD",
      "max_quantity": null
    }
  ],
  "status": "published"
}

Attraction — type: "attraction"

type_data fields

Pricing: keyed by variant_code (ticket code) × pax_type.
Availability: flat range — no variant breakdown required for simple products.

Example — ATT-01: Universal Studios (no time slots, 4 pax types)

{
  "operator": {
    "id": "a1b2c3d4-0005-0005-0005-000000000005",
    "slug": "sentosa-parks",
    "name": "Sentosa Parks & Attractions Pte Ltd"
  },
  "legacy_product_id": "ATT-USS-SGP",
  "type": "attraction",
  "name": "Universal Studios Singapore — General Admission",
  "description": "A full day of thrills, rides, and live shows at Universal Studios Singapore.",
  "destination": "Singapore",
  "country_code": "SG",
  "images": [{ "url": "https://cdn.example.com/uss1.jpg" }],
  "inclusions": ["Full-day general admission", "Access to all rides", "All live shows"],
  "exclusions": ["Universal Express Pass", "Food and beverages", "Merchandise"],
  "type_data": {
    "location_name": "Universal Studios Singapore",
    "address": "8 Sentosa Gateway, Singapore 098269",
    "latitude": 1.2540,
    "longitude": 103.8239,
    "operating_hours": [
      { "days": [0, 1, 2, 3, 4], "open": "10:00", "close": "21:00" },
      { "days": [5, 6],          "open": "10:00", "close": "22:00" }
    ],
    "ticket_types": [
      { "code": "ADT", "name": "Adult (13+)",   "pax_type": "adult"  },
      { "code": "CHD", "name": "Child (4–12)",  "pax_type": "child"  },
      { "code": "INF", "name": "Infant (0–3)",  "pax_type": "infant" },
      { "code": "SNR", "name": "Senior (60+)",  "pax_type": "senior" }
    ],
    "has_time_slots": false,
    "time_slots": [],
    "advance_booking_required_days": 1
  },
  "pricing": [
    { "variant_code": "ADT", "pax_type": "adult",  "amount": 88.00, "currency": "SGD" },
    { "variant_code": "CHD", "pax_type": "child",  "amount": 68.00, "currency": "SGD" },
    { "variant_code": "INF", "pax_type": "infant", "amount":  0.01, "currency": "SGD" },
    { "variant_code": "SNR", "pax_type": "senior", "amount": 68.00, "currency": "SGD" }
  ],
  "availability": [{ "start_date": "2026-07-01", "end_date": "2026-12-31", "total_allotment": 500 }],
  "status": "published"
}

Ferry — type: "ferry"

type_data fields

Pricing: keyed by variant_code (seat-class code) × pax_type. Flat-rate classes typically have only an adult row.

Example — FRY-02: Economy flat-rate + VIP per-pax (success scenario)

{
  "operator": {
    "id": "a1b2c3d4-0004-0004-0004-000000000004",
    "slug": "batam-fast-pte",
    "name": "Batam Fast Pte Ltd"
  },
  "legacy_product_id": "FRY-BF-SIN-BTM-VIP",
  "type": "ferry",
  "name": "Batam Fast — Singapore HarbourFront → Batam Centre (Economy & VIP)",
  "description": "Choose Economy or VIP class on Batam Fast's daily service. VIP class includes priority boarding, recliner seats, and complimentary refreshments.",
  "destination": "Batam",
  "country_code": "ID",
  "images": [{ "url": "https://cdn.example.com/batamfast-vip1.jpg" }],
  "inclusions": ["Ferry passage (one way)", "Terminal handling fees"],
  "exclusions": ["Indonesia departure tax", "Travel insurance"],
  "type_data": {
    "operator": "Batam Fast",
    "origin_port": "HarbourFront Terminal 1",
    "origin_port_code": "SGHHF",
    "destination_port": "Batam Centre Ferry Terminal",
    "destination_port_code": "BTMCF",
    "trip_type": "one_way",
    "schedule": [
      { "departure_time": "08:00", "arrival_time": "09:00", "days_of_week": [0,1,2,3,4,5,6] },
      { "departure_time": "10:30", "arrival_time": "11:30", "days_of_week": [0,1,2,3,4,5,6] },
      { "departure_time": "14:00", "arrival_time": "15:00", "days_of_week": [0,1,2,3,4,5,6] },
      { "departure_time": "17:00", "arrival_time": "18:00", "days_of_week": [0,1,2,3,4,5,6] }
    ],
    "seat_classes": [
      {
        "code": "ECO",
        "name": "Economy",
        "description": "Standard air-conditioned main deck seating.",
        "amenities": [],
        "is_flat_rate": true
      },
      {
        "code": "VIP",
        "name": "VIP Cabin",
        "description": "Private forward cabin. Recliner seats, priority boarding, bottled water and snack.",
        "amenities": ["priority_boarding", "refreshments", "wider_seats", "power_outlet"],
        "is_flat_rate": false
      }
    ]
  },
  "pricing": [
    { "variant_code": "ECO", "pax_type": "adult", "amount": 32.00, "currency": "SGD" },
    { "variant_code": "VIP", "pax_type": "adult", "amount": 58.00, "currency": "SGD" },
    { "variant_code": "VIP", "pax_type": "child", "amount": 45.00, "currency": "SGD" }
  ],
  "availability": [{ "start_date": "2026-07-01", "end_date": "2026-12-31", "total_allotment": 300 }],
  "status": "published"
}

Note: Economy is is_flat_rate: true with only an adult row. VIP is per-pax with adult and child rows.

Cruise — type: "cruise"

type_data fields

Top-level cruise extras:

Pricing (richer than current spec): keyed by variant_code (cabin code) × berth (double|single|extra) × pax_type.
Availability: includes cabin_allotments[] with { "variant_code": "INT", "total_allotment": 80 }. For named-cabin mode, add cabin_numbers[] array.

Example — CRU-01: 2-night round-trip, 3 cabin types (success scenario)

{
  "operator": {
    "id": "a1b2c3d4-0003-0003-0003-000000000003",
    "slug": "genting-cruises",
    "name": "Genting Cruise Lines"
  },
  "legacy_product_id": "CRU-GD-2N-RT",
  "type": "cruise",
  "name": "Genting Dream — 2N Weekend Getaway (Singapore Round-Trip)",
  "description": "A 2-night weekend cruise aboard Genting Dream. No port calls — pure ocean escape. Departs Friday evening, returns Sunday afternoon.",
  "destination": "International Waters",
  "country_code": "SG",
  "images": [{ "url": "https://cdn.example.com/genting-2n1.jpg" }],
  "inclusions": [
    "2-night cabin accommodation", "All meals at main dining restaurants",
    "Entertainment and shows", "Pool and gym access"
  ],
  "exclusions": ["Specialty dining", "Alcoholic beverages", "Spa treatments", "Gratuities"],
  "type_data": {
    "ship_name": "Genting Dream",
    "ship_operator": "Genting Cruise Lines",
    "route_name": "Singapore – International Waters – Singapore",
    "ports_of_call": [
      { "order": 1, "port": "Singapore (Marina Bay Cruise Centre)", "arrival": null,                  "departure": "2026-08-07T18:00:00" },
      { "order": 2, "port": "Singapore (Marina Bay Cruise Centre)", "arrival": "2026-08-09T14:00:00", "departure": null }
    ],
    "departure_date": "2026-08-07",
    "return_date":    "2026-08-09",
    "duration_nights": 2,
    "booking_unit": "per_cabin",
    "cabin_types": [
      {
        "code": "INT", "max_occupancy": 4, "min_occupancy": 2,
        "max_adults": 2, "max_children": 2, "max_infants": 1,
        "positions": [
          { "code": "forward", "price_modifier": 0  },
          { "code": "midship", "price_modifier": 50 },
          { "code": "aft",     "price_modifier": 30 }
        ]
      },
      {
        "code": "OCV", "max_occupancy": 4, "min_occupancy": 2,
        "max_adults": 2, "max_children": 2, "max_infants": 1,
        "positions": [
          { "code": "forward", "price_modifier": 0  },
          { "code": "midship", "price_modifier": 60 },
          { "code": "aft",     "price_modifier": 40 }
        ]
      },
      {
        "code": "BLC", "max_occupancy": 4, "min_occupancy": 2,
        "max_adults": 2, "max_children": 2, "max_infants": 1,
        "positions": [
          { "code": "forward", "price_modifier": 0  },
          { "code": "midship", "price_modifier": 80 },
          { "code": "aft",     "price_modifier": 60 }
        ]
      }
    ]
  },
  "pricing": [
    { "variant_code": "INT", "berth": "double", "pax_type": "adult",  "amount":  388.00, "currency": "SGD" },
    { "variant_code": "INT", "berth": "single", "pax_type": "adult",  "amount":  718.00, "currency": "SGD" },
    { "variant_code": "INT", "berth": "extra",  "pax_type": "adult",  "amount":  244.00, "currency": "SGD" },
    { "variant_code": "INT", "berth": "extra",  "pax_type": "child",  "amount":  237.00, "currency": "SGD" },
    { "variant_code": "INT", "berth": "extra",  "pax_type": "infant", "amount":  155.00, "currency": "SGD" },
    { "variant_code": "OCV", "berth": "double", "pax_type": "adult",  "amount":  488.00, "currency": "SGD" },
    { "variant_code": "OCV", "berth": "single", "pax_type": "adult",  "amount":  903.00, "currency": "SGD" },
    { "variant_code": "OCV", "berth": "extra",  "pax_type": "adult",  "amount":  307.00, "currency": "SGD" },
    { "variant_code": "OCV", "berth": "extra",  "pax_type": "child",  "amount":  297.00, "currency": "SGD" },
    { "variant_code": "OCV", "berth": "extra",  "pax_type": "infant", "amount":  195.00, "currency": "SGD" },
    { "variant_code": "BLC", "berth": "double", "pax_type": "adult",  "amount":  688.00, "currency": "SGD" },
    { "variant_code": "BLC", "berth": "single", "pax_type": "adult",  "amount": 1273.00, "currency": "SGD" },
    { "variant_code": "BLC", "berth": "extra",  "pax_type": "adult",  "amount":  433.00, "currency": "SGD" },
    { "variant_code": "BLC", "berth": "extra",  "pax_type": "child",  "amount":  420.00, "currency": "SGD" },
    { "variant_code": "BLC", "berth": "extra",  "pax_type": "infant", "amount":  275.00, "currency": "SGD" }
  ],
  "availability": [
    {
      "start_date": "2026-08-07",
      "end_date":   "2026-08-07",
      "total_allotment": 150,
      "cabin_allotments": [
        { "variant_code": "INT", "total_allotment": 80 },
        { "variant_code": "OCV", "total_allotment": 50 },
        { "variant_code": "BLC", "total_allotment": 20 }
      ]
    }
  ],
  "status": "published"
}

Transport — type: "transport"

Transport has three bookable sub-types, discriminated by type_data.transport_subtype: fix_route (fixed A→B private transfer), disposal (hourly charter), and sic (seat-in-coach shared transfer with customer-selected seats). Pricing and allotment for all three come from this Bridge API — there is no marketplace-admin-configured fare for any transport sub-type.

type_data fields (all sub-types)

Pricing:

• fix_route — one flat adult row = the whole-vehicle fare per direction, applied regardless of pax count. Do not publish a separate "return total" rule — round trip is booked as two legs, each resolving this same per-direction fare independently.
• disposal — one adult row = the per-hour rate. Booking fare = amount × hours_booked. There is no type_data.hourly_rate — the rate comes from this pricing[] array, same channel as every other sub-type.
• sic — one row per pax_type (age-tiered; infants ride free — omit or send amount: 0.00). Add variant_code = a slot's pickup_time to vary the fare per departure; omit variant_code for one uniform fare across all slots.

Example — TRN-01: Fixed MPV, Singapore Changi → Batam Nongsa, round-trip capable (success scenario)

{
  "operator": {
    "id": "a1b2c3d4-0004-0004-0004-000000000004",
    "slug": "batam-fast-pte",
    "name": "Batam Fast Pte Ltd"
  },
  "legacy_product_id": "TRN-FIXROUTE-SIN-BTM",
  "type": "transport",
  "name": "Singapore Changi Airport → Batam (Nongsa) — Private MPV",
  "description": "Private air-conditioned MPV transfer from any Changi Airport terminal to Nongsa, Batam. Meet-and-greet at the arrival hall. Up to 7 passengers.",
  "destination": "Batam",
  "country_code": "ID",
  "images": [{ "url": "https://cdn.example.com/mpv-sin-btm1.jpg" }],
  "inclusions": ["Meet & greet at arrival hall", "Up to 7 passengers", "Up to 7 pieces of luggage"],
  "exclusions": ["Ferry ticket (book separately)", "Tolls and parking fees"],
  "type_data": {
    "transport_subtype": "fix_route",
    "vehicle_type": "mpv",
    "vehicle_model": "Toyota Alphard or equivalent",
    "capacity_pax": 7,
    "capacity_luggage": 7,
    "trip_type": "return",
    "pricing_method": "fixed",
    "minimum_pax": 1,
    "is_cross_border": true,
    "pickup_locations": [
      { "code": "SIN_T1", "name": "Changi Airport Terminal 1", "city": "Singapore", "country": "SG" },
      { "code": "SIN_T3", "name": "Changi Airport Terminal 3", "city": "Singapore", "country": "SG" }
    ],
    "dropoff_locations": [
      { "code": "BTM_NONGSA", "name": "Nongsa District, Batam", "city": "Batam", "country": "ID" }
    ],
    "time_slots": [
      { "code": "AM1", "pickup_time": "08:00", "turnaround_minutes": 240 },
      { "code": "PM1", "pickup_time": "14:00", "turnaround_minutes": 240 }
    ],
    "distance_km": null,
    "features": ["aircon", "wifi", "bottled_water"]
  },
  "pricing": [
    { "pax_type": "adult", "amount": 120.00, "currency": "SGD" }
  ],
  "availability": [{ "start_date": "2026-07-01", "end_date": "2026-12-31", "total_allotment": 5 }],
  "status": "published"
}

Note: trip_type: "return" means the marketplace can book this product as a 2-leg round trip (one booking, two ERP holds — one per leg's date). is_cross_border: true is valid here because pickup (SG) and dropoff (ID) resolve to different countries. time_slots[] is optional for fix_route; the customer's requested time must match a slot's pickup_time when present, not the code.

Example — TRN-06: Hourly disposal MPV, Singapore (success scenario)

{
  "operator": {
    "id": "a1b2c3d4-0004-0004-0004-000000000004",
    "slug": "batam-fast-pte",
    "name": "Batam Fast Pte Ltd"
  },
  "legacy_product_id": "TRN-DISPOSAL-SGP",
  "type": "transport",
  "name": "Singapore — Hourly Disposal MPV (Min 4 Hours)",
  "description": "Dedicated private MPV for sightseeing or errands. Minimum 4-hour booking.",
  "destination": "Singapore",
  "country_code": "SG",
  "images": [{ "url": "https://cdn.example.com/hourly-mpv1.jpg" }],
  "inclusions": ["Dedicated driver for booked hours", "Fuel, ERP, and CBD parking"],
  "exclusions": ["Parking beyond 2 stops", "Gratuities"],
  "type_data": {
    "transport_subtype": "disposal",
    "vehicle_type": "mpv",
    "vehicle_model": "Toyota Alphard or equivalent",
    "capacity_pax": 7,
    "capacity_luggage": 5,
    "pricing_method": "per_hour",
    "minimum_hours": 4,
    "maximum_hours": 8,
    "operating_area": "Singapore (all districts)",
    "operating_hours": { "start": "07:00", "end": "23:00" },
    "features": ["aircon", "flexible_itinerary"]
  },
  "pricing": [
    { "pax_type": "adult", "amount": 45.00, "currency": "SGD" }
  ],
  "availability": [{ "start_date": "2026-07-01", "end_date": "2026-12-31", "total_allotment": 5 }],
  "status": "published"
}

Note: amount is the per-hour rate; total fare at booking = amount × hours_booked. A disposal product published with no pricing[] row prices at 0.00 — always include a base adult rate.

Example — TRN-09: Seat-in-coach, Sentosa → City Hotels (success scenario)

{
  "operator": {
    "id": "a1b2c3d4-0004-0004-0004-000000000004",
    "slug": "batam-fast-pte",
    "name": "Batam Fast Pte Ltd"
  },
  "legacy_product_id": "TRN-SIC-SENTOSA-CITY",
  "type": "transport",
  "name": "Sentosa → City Hotels — Seat-in-Coach Transfer",
  "description": "Shared coach transfer; select your own seats.",
  "destination": "Singapore",
  "country_code": "SG",
  "images": [{ "url": "https://cdn.example.com/sic-coach1.jpg" }],
  "inclusions": ["Reserved seat", "Air-conditioned coach"],
  "exclusions": ["Meals", "Gratuities"],
  "type_data": {
    "transport_subtype": "sic",
    "vehicle_type": "coach",
    "vehicle_model": "Higer Coach or equivalent",
    "capacity_pax": 49,
    "pricing_method": "per_seat",
    "minimum_pax": 2,
    "pickup_locations": [
      { "code": "SENTOSA", "name": "Sentosa Coach Park", "city": "Singapore", "country": "SG" }
    ],
    "dropoff_locations": [
      { "code": "CITY", "name": "City Hotels", "city": "Singapore", "country": "SG" }
    ],
    "seat_layout": {
      "seats": [
        { "number": "1", "row": 1, "col": "A" },
        { "number": "2", "row": 1, "col": "B" },
        { "number": "3", "row": 1, "col": "C" },
        { "number": "4", "row": 1, "col": "D" }
      ]
    },
    "time_slots": [
      { "code": "PM8", "pickup_time": "20:15", "turnaround_minutes": 60 }
    ],
    "features": ["aircon", "wifi"]
  },
  "pricing": [
    { "pax_type": "adult", "amount": 25.00, "currency": "SGD" },
    { "pax_type": "child", "amount": 18.00, "currency": "SGD" }
  ],
  "availability": [{ "start_date": "2026-07-01", "end_date": "2026-12-31", "total_allotment": 1 }],
  "status": "published"
}

Note: seat_layout.seats[].number must be unique; row/col are display-only (frontend seat-grid). time_slots[] is required for sic, with a unique code. The availability[] block above is only the coarse listing seed — actual seat inventory is per-schedule via stock.updated, see Seat-in-Coach allotment below.

Errors & Status Codes

Product Sync · Bridge API

How Stock Sync Works

The ERP owns availability. The Marketplace maintains a read-only product_availability mirror of whatever the ERP pushes. This mirror drives the "available / sold out" status shown to B2C customers and is the basis for hold/confirm decisions.

Two write paths — which one to use

Authentication

Stock Sync

The stock webhook uses HMAC-SHA256 request signing — no API key. Request a webhook HMAC secret from EZCore; it is a shared secret and is never sent as a header. Every request must include two extra headers, where the signature is an HMAC-SHA256 digest of the string "{timestamp}.{raw_body}" using that secret.

Signing example

TS=$(date +%s)
BODY='{"event":"stock.updated","event_id":"EVT-001","legacy_product_id":"PKG-BALI-5D4N","emitted_at":"2026-07-01T10:00:00Z","changes":[{"date":"2026-08-01","total_allotment":100,"available":95}]}'

SIG=$(printf '%s.%s' "$TS" "$BODY" \
  | openssl dgst -sha256 -hmac "$STOCK_WEBHOOK_SECRET" \
  | sed 's/^.* //')

curl -X POST https://api-marketplace.ezbcloud.space/api/marketplace/webhooks/stock \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Timestamp: $TS" \
  -H "X-Webhook-Signature: sha256=$SIG" \
  -d "$BODY"

<?php

$secret = getenv('STOCK_WEBHOOK_SECRET');
$url    = 'https://api-marketplace.ezbcloud.space/api/marketplace/webhooks/stock';

$ts   = (string) time();
$body = json_encode([
    'event'             => 'stock.updated',
    'event_id'          => 'EVT-001',
    'legacy_product_id' => 'PKG-BALI-5D4N',
    'emitted_at'        => '2026-07-01T10:00:00Z',
    'changes'           => [
        ['date' => '2026-08-01', 'total_allotment' => 100, 'available' => 95],
    ],
], JSON_UNESCAPED_SLASHES);

// Sign "{timestamp}.{raw_body}" with the shared HMAC secret
$signature = hash_hmac('sha256', $ts . '.' . $body, $secret);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-Webhook-Timestamp: ' . $ts,
        'X-Webhook-Signature: sha256=' . $signature,
    ],
    CURLOPT_POSTFIELDS     => $body,
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "HTTP {$status}\n{$response}\n";

stock.updated Webhook

Request body — StockUpdatedRequest

StockChange — two shapes

Each entry in changes[] is either a single date or a date-range:

Key behaviours

Stock Webhook — Payload Examples

{
  "event": "stock.updated",
  "event_id": "EVT-PKG-BALI-20260801",
  "legacy_product_id": "PKG-BALI-5D4N",
  "emitted_at": "2026-08-01T09:00:00Z",
  "changes": [
    {
      "date": "2026-08-15",
      "total_allotment": 22,
      "available": 20,
      "reason": "b2b_booking_placed",
      "reference": "BKG-20260801-001"
    }
  ]
}

{
  "event": "stock.updated",
  "event_id": "EVT-USS-BLACKOUT-20261225",
  "legacy_product_id": "ATT-USS-SGP",
  "emitted_at": "2026-07-01T00:00:00Z",
  "changes": [
    {
      "date": "2026-12-25",
      "total_allotment": 0,
      "available": 0,
      "is_blackout": true,
      "reason": "manual_adjustment"
    }
  ]
}

{
  "event": "stock.updated",
  "event_id": "EVT-HTL-MID-20260901",
  "legacy_product_id": "HTL-MID-SGP-002",
  "emitted_at": "2026-09-01T08:00:00Z",
  "changes": [
    { "date": "2026-09-15", "variant_code": "std", "total_allotment": 50, "available": 48, "reason": "erp_sync" },
    { "date": "2026-09-15", "variant_code": "dlx", "total_allotment": 30, "available": 29, "reason": "erp_sync" }
  ]
}

{
  "event": "stock.updated",
  "event_id": "EVT-SEA-SLOT-20260801",
  "legacy_product_id": "ATT-SEA-SGP",
  "emitted_at": "2026-08-01T07:00:00Z",
  "changes": [
    {
      "date": "2026-08-20",
      "variant_code": "ADT",
      "session_time": "10:00",
      "session_end_time": "12:00",
      "total_allotment": 80,
      "available": 75,
      "reason": "b2b_booking_placed"
    }
  ]
}

{
  "event": "stock.updated",
  "event_id": "EVT-HTL-RANGE-Q4",
  "legacy_product_id": "HTL-MID-SGP-002",
  "emitted_at": "2026-07-01T00:00:00Z",
  "changes": [
    {
      "start_date": "2026-10-01",
      "end_date": "2026-12-31",
      "total_allotment": 80,
      "available": 80,
      "reason": "erp_sync",
      "variant_allotments": [
        { "variant_code": "std", "total_allotment": 50, "available": 50 },
        { "variant_code": "dlx", "total_allotment": 30, "available": 30 }
      ]
    }
  ]
}

{
  "event": "stock.updated",
  "event_id": "EVT-SIC-SENTOSA-20260615",
  "legacy_product_id": "TRN-SIC-SENTOSA-CITY",
  "emitted_at": "2026-06-15T02:00:00Z",
  "changes": [
    { "date": "2026-09-01", "session_time": "20:15", "total_allotment": 2, "available": 2, "is_blackout": false, "reason": "manual_allotment_change" },
    { "date": "2026-09-01", "session_time": "22:00", "total_allotment": 1, "available": 1, "is_blackout": false, "reason": "manual_allotment_change" },
    { "date": "2026-09-02", "session_time": "20:15", "total_allotment": 2, "available": 2, "is_blackout": false, "reason": "manual_allotment_change" }
  ]
}

Response — WebhookDispatchResponse

{
  "event_id": "EVT-PKG-BALI-20260801",
  "status": "processed",
  "id": "wh-dispatch-uuid",
  "duplicate": false
}

Sequence diagram

Triggers & Verification ERP → Marketplace

The ERP emits a stock.updated event whenever stock moves for any reason — this is the only thing that keeps the marketplace mirror correct against invisible B2B activity. The field-level reference is above in stock.updated Webhook; below are the booking-context triggers and how the marketplace verifies the signature.

Triggers — emit on ALL of these

Required headers

X-Api-Key:           <bridge-api-key>
X-Webhook-Signature: sha256=<hex_hmac>
X-Webhook-Timestamp: <unix_epoch_seconds>
Content-Type:        application/json

How the marketplace verifies the ERP

The receiver runs this check (real code, WebhookVerificationService):

1. Require X-Webhook-Signature and X-Webhook-Timestamp, else 400.
2. abs(now − X-Webhook-Timestamp) must be ≤ 300s, else 400 "outside replay window".
3. computed = HMAC_SHA256("{timestamp}.{raw_body}", STOCK_WEBHOOK_SECRET). Compare against hex in "sha256=<hex>". Mismatch → 401.
4. Body must be a JSON object with non-empty event and event_id, else 400.

Signing recipe (pseudocode, ERP side)

ts        = current_unix_seconds()
raw_body  = json_encode(payload)          # sign the EXACT bytes sent
to_sign   = ts + "." + raw_body
signature = "sha256=" + hex( hmac_sha256(to_sign, STOCK_WEBHOOK_SECRET) )
# headers: X-Webhook-Timestamp: ts, X-Webhook-Signature: signature

Delivery Status Poll

Poll delivery status before retrying a failed webhook. Replace {source} with stock. Auth: X-Api-Key only (no HMAC required for reads). Rate limit: 120 requests/min.

Response — WebhookEvent fields

ERP retry decision matrix

Sequence diagram

Errors & Status Codes

Stock Sync

Booking

The one rule

The ERP is the single source of truth for all stock. The marketplace never owns inventory. It keeps a display-only mirror of availability and asks the ERP for every real stock decision.

Why this matters: the ERP already serves B2B traffic (agent, corporate, walk-in) that the marketplace cannot see. If the marketplace counted stock locally, it would oversell the moment a B2B booking is taken on the ERP side. So all hold / release / confirm decisions run through the ERP.

The ERP team builds three surfaces:

System Map

Stock decisions are 100% ERP. The marketplace has no on_hold / booked state and no SELECT FOR UPDATE on stock. Payments run through pay.acetours.sg (ERP), Stripe, or FOMO Pay — selectable per tenant (see Payment Providers and Auth & Config).

Stock Operations API ERP hosts

Synchronous HTTP API hosted on the ERP side. The marketplace calls it during the booking flow. Three endpoints.

Hold lifecycle (ERP side)

GET /stock/availability Marketplace → ERP

Real-time stock check. Called at booking creation just before a hold (and optionally for calendar refresh).

Query parameters

Request & Response

GET /api/marketplace/stock/availability
  ?product_id=PKG-001
  &start_date=2026-06-01
  &end_date=2026-06-30
  &variant_code=DLX_DBL

{
  "data": [
    { "date": "2026-06-15", "total_allotment": 6, "available": 6, "is_blackout": false, "variant_code": "DLX_DBL", "session_time": null, "session_end_time": null },
    { "date": "2026-06-16", "total_allotment": 6, "available": 0, "is_blackout": false, "variant_code": "DLX_DBL", "session_time": null, "session_end_time": null },
    { "date": "2026-06-17", "total_allotment": 6, "available": 6, "is_blackout": true,  "variant_code": "DLX_DBL", "session_time": null, "session_end_time": null }
  ]
}

available = real bookable count right now (allotment minus all holds and bookings, B2B + B2C). is_blackout: true means not sellable regardless of count. total_allotment is required on every row; available defaults to it if omitted.

session_time / session_end_time (nullable) carry the scheduled departure/slot for time-slotted products — timed-entry attractions, ferry sailings, and transport fix_route (when the product has configured time_slots[]) or sic (always required). One row per (date, session_time) for these products, not one row per date.

Multi-room / multi-cabin: POST /stock/availability/batch

The GET endpoint above checks one variant_code at a time, so it can't answer "is this exact combination of rooms/cabins available together" in one round trip. For a multi-unit booking (e.g. 1 std + 1 dlx hotel room, or 2 cruise cabins of different types) the marketplace instead calls a batch endpoint just before placing the batch of holds, so it can tell the customer which specific unit is unavailable and let them swap it before committing to a hold.

Request fields

Request & Response

{
  "product_id": "HTL-MID-SGP-002",
  "date": "2026-09-10",
  "units": [
    { "variant_code": "std", "quantity": 1 },
    { "variant_code": "dlx", "quantity": 1 }
  ]
}

{
  "units": [
    { "variant_code": "std", "position": 1, "available": true,  "available_qty": 4 },
    { "variant_code": "dlx", "position": 2, "available": false, "available_qty": 0 }
  ]
}

Response is purely per-unit — there's no overall/aggregate status field, the marketplace derives "can this booking proceed" by checking every entry's available. position is the 1-based index of that unit within the request's units array (mirrors unit_position in booking.confirmed) so the marketplace can map a result back to the room/cabin the customer picked, even with repeated variant_codes (e.g. two std rooms). available_qty defaults to 0 if omitted.

POST /stock/holds Marketplace → ERP

Place a hold. This is the gate — the marketplace creates a booking record only after this returns success.

Request fields

Request & Response

{
  "product_id": "PKG-001",
  "date": "2026-06-15",
  "quantity": 1,
  "variant_code": "DLX_DBL",
  "session_time": null
}

{
  "hold_id": "HOLD-ERP-00789"
}

{
  "error": "insufficient_stock",
  "available": 1,
  "requested": 2
}

Multi-room / multi-cabin: POST /stock/holds/batch

The endpoint above places one hold at a time, so it can't atomically commit a multi-unit booking (e.g. 1 std + 1 dlx hotel room, or several cruise cabins) — a partial success would leave some rooms held and others not. The marketplace instead calls a batch endpoint once per booking (once per night for multi-night stays), right after the availability/batch precheck, so the whole set of holds either succeeds together or fails with per-unit detail the customer can act on.

Request fields

Request & Response

{
  "product_id": "HTL-MID-SGP-002",
  "date": "2026-09-10",
  "units": [
    { "variant_code": "std", "quantity": 1 },
    { "variant_code": "dlx", "quantity": 1 }
  ],
  "session_time": null
}

{
  "hold_id": "BATCH-HOLD-00123",
  "unit_holds": [
    { "variant_code": "std", "unit_hold_id": "UNIT-HOLD-00456" },
    { "variant_code": "dlx", "unit_hold_id": "UNIT-HOLD-00457" }
  ]
}

{
  "unavailable_units": [
    { "variant_code": "dlx", "position": 2 }
  ]
}

hold_id is the batch-level id for the whole set; unit_holds gives one hold id per unit, in request order. On 409, unavailable_units names exactly which unit(s) conflicted — by variant_code and 1-based position in the request's units array — so the marketplace can prompt the customer to swap just that room/cabin instead of failing the whole booking. This is more detail than availability/batch gives on a non-200 (see above); unlike that endpoint, a conflict here is expected to identify the exact unit(s), not just fail generically.

DELETE /stock/holds/{hold_id} Marketplace → ERP

Release a hold. Called on: payment failure, 15-min expiry (marketplace cleanup job), or cancellation. No request body — hold_id in path.

Response 200

{ "hold_id": "HOLD-ERP-00789", "status": "released" }

Response (already released / unknown — treat as success)

{ "error": "hold_not_found" }

Booking Webhook Receiver Marketplace → ERP

The marketplace calls the ERP when a booking is confirmed or cancelled. The ERP hosts this endpoint. Respond within 10s — acknowledge with 202 Accepted and process async if needed.

Auth headers the ERP receives

The ERP verifies exactly like the Stock Sync webhook (same "{timestamp}.{raw_body}" HMAC scheme, shared webhook_secret). Reject requests older than 5 min (replay protection).

Event: booking.confirmed

This is where the ERP converts the hold into a real booking, and — for stock_upload products — triggers the Pre-Uploaded Voucher callback.

Example payloads by product type

The envelope is shared across all product types — only a handful of fields (trip_type, check_out_date, units[], open_ticket, transport, e_ticket_delivery_method) vary. Each tab below confirms a booking for the same example product already published via the Bridge Product API in Product Types & type_data, so you can trace one product all the way from publish → book → confirm. payment.method is shown as null in every example — it's reserved for a future PaymentDomain field and is not populated by the current webhook sender regardless of how the customer actually paid.

{
  "event": "booking.confirmed",
  "platform_booking_id": "0198f2b1-2a44-7c31-9b10-000000000101",
  "booking_reference": "BK-2026-01001",
  "legacy_product_id": "PKG-BIN-3D2N-COMP",
  "legacy_hold_id": "HOLD-ERP-01001",
  "legacy_hold_ids": null,
  "trip_type": null,
  "travel_date": "2026-08-15",
  "check_out_date": null,
  "pax": { "adults": 2, "children": 1, "infants": 0 },
  "passengers": [
    { "type": "adult", "name": "John Doe", "passport": "E1234567", "nationality": "SG", "dob": "1985-03-12" },
    { "type": "adult", "name": "Jane Doe", "passport": "E7654321", "nationality": "SG", "dob": "1988-07-22" },
    { "type": "child", "name": "Tom Doe",  "passport": null,        "nationality": "SG", "dob": "2018-05-10" }
  ],
  "units": [],
  "customer": { "name": "John Doe", "email": "john@example.com", "phone": "+6591234567" },
  "payment": { "amount": 1077.06, "currency": "SGD", "method": null, "provider": "acetours_pay", "reference": "PAY-AT-000123" },
  "tax_summary": {
    "destination_scope": "international",
    "tax_lines": [
      { "name": "Zero-rated (Outbound)", "tax_type": "zero_rated", "rate": 0.00, "amount": "0.00", "inclusive": true }
    ],
    "embedded_tax_total": "0.00",
    "added_tax_total":    "0.00",
    "tax_total":          "0.00",
    "tax_note":           "Zero-rated supply — outbound tour package"
  },
  "confirmed_at": "2026-07-16T09:12:00Z",
  "open_ticket": null,
  "transport": null,
  "e_ticket_delivery_method": "auto_generate"
}

{
  "event": "booking.confirmed",
  "platform_booking_id": "0198f2b1-3b55-7c42-9b10-000000000201",
  "booking_reference": "BK-2026-01002",
  "legacy_product_id": "HTL-MID-SGP-002",
  "legacy_hold_id": "HOLD-ERP-01002",
  "legacy_hold_ids": ["HOLD-ERP-01002", "HOLD-ERP-01003"],
  "trip_type": null,
  "travel_date": "2026-09-10",
  "check_out_date": "2026-09-12",
  "pax": { "adults": 4, "children": 1, "infants": 0 },
  "passengers": [
    { "type": "adult", "name": "Alice Tan", "passport": "E1111111", "nationality": "SG", "dob": "1990-01-15" },
    { "type": "adult", "name": "Bob Tan",   "passport": "E2222222", "nationality": "SG", "dob": "1988-06-20" },
    { "type": "adult", "name": "Carol Lim", "passport": "E3333333", "nationality": "SG", "dob": "1992-03-10" },
    { "type": "adult", "name": "David Lim", "passport": "E4444444", "nationality": "SG", "dob": "1989-11-05" },
    { "type": "child", "name": "Ellie Lim", "passport": null,        "nationality": "SG", "dob": "2019-05-02" }
  ],
  "units": [
    {
      "unit_position": 1,
      "variant_code": "std",
      "pax": { "adults": 2, "children": 0, "infants": 0 },
      "passengers": [
        { "type": "adult", "name": "Alice Tan", "passport": "E1111111", "nationality": "SG", "dob": "1990-01-15" },
        { "type": "adult", "name": "Bob Tan",   "passport": "E2222222", "nationality": "SG", "dob": "1988-06-20" }
      ],
      "legacy_hold_id": "HOLD-ERP-01002-U1",
      "legacy_hold_ids": ["HOLD-ERP-01002-U1", "HOLD-ERP-01003-U1"],
      "total_amount": 592.00,
      "type_data": null
    },
    {
      "unit_position": 2,
      "variant_code": "dlx",
      "pax": { "adults": 2, "children": 1, "infants": 0 },
      "passengers": [
        { "type": "adult", "name": "Carol Lim", "passport": "E3333333", "nationality": "SG", "dob": "1992-03-10" },
        { "type": "adult", "name": "David Lim", "passport": "E4444444", "nationality": "SG", "dob": "1989-11-05" },
        { "type": "child", "name": "Ellie Lim", "passport": null,        "nationality": "SG", "dob": "2019-05-02" }
      ],
      "legacy_hold_id": "HOLD-ERP-01002-U2",
      "legacy_hold_ids": ["HOLD-ERP-01002-U2", "HOLD-ERP-01003-U2"],
      "total_amount": 752.02,
      "type_data": null
    }
  ],
  "customer": { "name": "Alice Tan", "email": "alice.tan@example.com", "phone": "+6598765432" },
  "payment": { "amount": 1344.02, "currency": "SGD", "method": null, "provider": "acetours_pay", "reference": "PAY-AT-000201" },
  "tax_summary": {
    "destination_scope": "domestic",
    "tax_lines": [
      { "name": "GST (9%)", "tax_type": "gst", "rate": 0.09, "amount": "110.97", "inclusive": true }
    ],
    "embedded_tax_total": "110.97",
    "added_tax_total":    "0.00",
    "tax_total":          "110.97",
    "tax_note":           "Prices inclusive of 9% GST"
  },
  "confirmed_at": "2026-07-16T10:05:00Z",
  "open_ticket": null,
  "transport": null,
  "e_ticket_delivery_method": "auto_generate"
}

{
  "event": "booking.confirmed",
  "platform_booking_id": "0198f2b1-4c66-7c53-9b10-000000000301",
  "booking_reference": "BK-2026-01003",
  "legacy_product_id": "CRU-GD-2N-RT",
  "legacy_hold_id": "HOLD-ERP-01004",
  "legacy_hold_ids": null,
  "trip_type": null,
  "travel_date": "2026-08-07",
  "check_out_date": "2026-08-09",
  "pax": { "adults": 4, "children": 1, "infants": 0 },
  "passengers": [
    { "type": "adult", "name": "Marcus Yeo",  "passport": "E5551001", "nationality": "SG", "dob": "1982-02-14" },
    { "type": "adult", "name": "Serene Yeo",  "passport": "E5551002", "nationality": "SG", "dob": "1984-10-09" },
    { "type": "adult", "name": "Ivan Koh",    "passport": "E5551003", "nationality": "SG", "dob": "1979-05-30" },
    { "type": "adult", "name": "Grace Koh",   "passport": "E5551004", "nationality": "SG", "dob": "1981-12-02" },
    { "type": "child", "name": "Bella Koh",   "passport": null,        "nationality": "SG", "dob": "2017-08-19" }
  ],
  "units": [
    {
      "unit_position": 1,
      "variant_code": "INT",
      "pax": { "adults": 2, "children": 0, "infants": 0 },
      "passengers": [
        { "type": "adult", "name": "Marcus Yeo", "passport": "E5551001", "nationality": "SG", "dob": "1982-02-14" },
        { "type": "adult", "name": "Serene Yeo", "passport": "E5551002", "nationality": "SG", "dob": "1984-10-09" }
      ],
      "legacy_hold_id": "HOLD-ERP-01004-U1",
      "legacy_hold_ids": null,
      "total_amount": 776.00,
      "type_data": {
        "cabin_code": "INT",
        "tax_summary": {
          "destination_scope": "domestic",
          "tax_lines": [ { "name": "GST (9%)", "tax_type": "gst", "rate": 0.09, "amount": "64.07", "inclusive": true } ],
          "embedded_tax_total": "64.07",
          "added_tax_total":    "0.00",
          "tax_total":          "64.07",
          "tax_note":           "Prices inclusive of 9% GST"
        }
      }
    },
    {
      "unit_position": 2,
      "variant_code": "BLC",
      "pax": { "adults": 2, "children": 1, "infants": 0 },
      "passengers": [
        { "type": "adult", "name": "Ivan Koh",  "passport": "E5551003", "nationality": "SG", "dob": "1979-05-30" },
        { "type": "adult", "name": "Grace Koh", "passport": "E5551004", "nationality": "SG", "dob": "1981-12-02" },
        { "type": "child", "name": "Bella Koh", "passport": null,        "nationality": "SG", "dob": "2017-08-19" }
      ],
      "legacy_hold_id": "HOLD-ERP-01004-U2",
      "legacy_hold_ids": null,
      "total_amount": 1796.00,
      "type_data": {
        "cabin_code": "BLC",
        "tax_summary": {
          "destination_scope": "domestic",
          "tax_lines": [ { "name": "GST (9%)", "tax_type": "gst", "rate": 0.09, "amount": "148.29", "inclusive": true } ],
          "embedded_tax_total": "148.29",
          "added_tax_total":    "0.00",
          "tax_total":          "148.29",
          "tax_note":           "Prices inclusive of 9% GST"
        }
      }
    }
  ],
  "customer": { "name": "Marcus Yeo", "email": "marcus.yeo@example.com", "phone": "+6591230001" },
  "payment": { "amount": 2572.00, "currency": "SGD", "method": null, "provider": "acetours_pay", "reference": "PAY-AT-000301" },
  "tax_summary": {
    "destination_scope": "domestic",
    "tax_lines": [
      { "name": "GST (9%)", "tax_type": "gst", "rate": 0.09, "amount": "212.36", "inclusive": true }
    ],
    "embedded_tax_total": "212.36",
    "added_tax_total":    "0.00",
    "tax_total":          "212.36",
    "tax_note":           "Prices inclusive of 9% GST"
  },
  "confirmed_at": "2026-07-16T11:40:00Z",
  "open_ticket": null,
  "transport": null,
  "e_ticket_delivery_method": "auto_generate"
}

{
  "event": "booking.confirmed",
  "platform_booking_id": "0198f2b1-5d77-7c64-9b10-000000000401",
  "booking_reference": "BK-2026-01004",
  "legacy_product_id": "FRY-BF-SIN-BTM-VIP",
  "legacy_hold_id": "HOLD-ERP-01005",
  "legacy_hold_ids": null,
  "trip_type": "one_way",
  "travel_date": "2026-09-05",
  "check_out_date": null,
  "pax": { "adults": 1, "children": 1, "infants": 0 },
  "passengers": [
    { "type": "adult", "name": "Michael Tan", "passport": "E8888001", "nationality": "SG", "dob": "1980-01-01" },
    { "type": "child", "name": "Nathan Tan",  "passport": null,        "nationality": "SG", "dob": "2015-06-06" }
  ],
  "units": [],
  "customer": { "name": "Michael Tan", "email": "michael.tan@example.com", "phone": "+6591230002" },
  "payment": { "amount": 121.00, "currency": "SGD", "method": null, "provider": "acetours_pay", "reference": "PAY-AT-000401" },
  "tax_summary": {
    "destination_scope": "domestic",
    "tax_lines": [
      { "name": "GST (9%)",             "tax_type": "gst",      "rate": 0.09, "amount": "8.50",  "inclusive": true  },
      { "name": "Batam Departure Levy", "tax_type": "port_tax", "rate": 0.00, "amount": "18.00", "inclusive": false }
    ],
    "embedded_tax_total": "8.50",
    "added_tax_total":    "18.00",
    "tax_total":          "26.50",
    "tax_note":           "Prices inclusive of 9% GST. Port levy SGD 18.00/adult passenger (children exempt) collected on behalf of Batam Port Authority."
  },
  "confirmed_at": "2026-07-16T13:22:00Z",
  "open_ticket": null,
  "transport": null,
  "e_ticket_delivery_method": "stock_upload"
}

"open_ticket": {
  "is_open_ticket": true,
  "validity_start": "departure_date",
  "valid_until": "2026-12-04"
}

{
  "event": "booking.confirmed",
  "platform_booking_id": "0198f2b1-6e88-7c75-9b10-000000000501",
  "booking_reference": "BK-2026-01005",
  "legacy_product_id": "ATT-USS-SGP",
  "legacy_hold_id": "HOLD-ERP-01006",
  "legacy_hold_ids": null,
  "trip_type": null,
  "travel_date": "2026-08-20",
  "check_out_date": null,
  "pax": { "adults": 2, "children": 1, "infants": 0 },
  "passengers": [
    { "type": "adult", "name": "Wei Ling Ng", "passport": "E9990001", "nationality": "SG", "dob": "1986-04-11" },
    { "type": "adult", "name": "Kok Seng Ng", "passport": "E9990002", "nationality": "SG", "dob": "1984-09-23" },
    { "type": "child", "name": "Mei Ng",      "passport": null,        "nationality": "SG", "dob": "2020-02-14" }
  ],
  "units": [],
  "customer": { "name": "Wei Ling Ng", "email": "weiling.ng@example.com", "phone": "+6591230003" },
  "payment": { "amount": 244.00, "currency": "SGD", "method": null, "provider": "acetours_pay", "reference": "PAY-AT-000501" },
  "tax_summary": {
    "destination_scope": "domestic",
    "tax_lines": [
      { "name": "GST (9%)", "tax_type": "gst", "rate": 0.09, "amount": "20.15", "inclusive": true }
    ],
    "embedded_tax_total": "20.15",
    "added_tax_total":    "0.00",
    "tax_total":          "20.15",
    "tax_note":           "Prices inclusive of 9% GST"
  },
  "confirmed_at": "2026-07-16T14:50:00Z",
  "open_ticket": null,
  "transport": null,
  "e_ticket_delivery_method": "auto_generate"
}

{
  "event": "booking.confirmed",
  "platform_booking_id": "0198f2b1-7f99-7c86-9b10-000000000601",
  "booking_reference": "BK-2026-01006",
  "legacy_product_id": "TRN-FIXROUTE-SIN-BTM",
  "legacy_hold_id": "HOLD-ERP-01007",
  "trip_type": null,
  "travel_date": "2026-08-25",
  "pax": { "adults": 2, "children": 0, "infants": 0 },
  "passengers": [
    { "type": "adult", "name": "Farah Rahman", "passport": "E1230001", "nationality": "SG", "dob": "1991-07-03" },
    { "type": "adult", "name": "Yusuf Rahman", "passport": "E1230002", "nationality": "SG", "dob": "1990-11-19" }
  ],
  "customer": { "name": "Farah Rahman", "email": "farah.rahman@example.com", "phone": "+6591230004" },
  "payment": { "amount": 120.00, "currency": "SGD", "method": null, "provider": "acetours_pay", "reference": "PAY-AT-000601" },
  "tax_summary": {
    "destination_scope": "international",
    "tax_lines": [
      { "name": "Zero-rated (Outbound)", "tax_type": "zero_rated", "rate": 0.00, "amount": "0.00", "inclusive": true }
    ],
    "embedded_tax_total": "0.00",
    "added_tax_total":    "0.00",
    "tax_total":          "0.00",
    "tax_note":           "Zero-rated supply — outbound transport service"
  },
  "confirmed_at": "2026-07-16T15:33:00Z",
  "open_ticket": null,
  "transport": {
    "transport_subtype": "fix_route",
    "trip_type": null,
    "pickup_location": "SIN_T1",
    "dropoff_location": "BTM_NONGSA",
    "session_time": null,
    "selected_seats": null
  },
  "legacy_hold_ids": null,
  "e_ticket_delivery_method": "auto_generate"
}

{
  "event": "booking.confirmed",
  "legacy_product_id": "TRN-SIC-SENTOSA-CITY",
  "legacy_hold_id": "HOLD-ERP-02001",
  "legacy_hold_ids": ["HOLD-ERP-02001", "HOLD-ERP-02002"],
  "transport": {
    "transport_subtype": "sic",
    "trip_type": null,
    "legs": [
      {
        "leg_position": 1,
        "legacy_product_id": "TRN-SIC-SENTOSA-CITY",
        "legacy_hold_id": "HOLD-ERP-02001",
        "travel_date": "2026-09-01",
        "session_time": "20:15",
        "pickup_location": null,
        "dropoff_location": null,
        "selected_seats": ["12", "13"]
      },
      {
        "leg_position": 2,
        "legacy_product_id": "TRN-SIC-CITY-SENTOSA",
        "legacy_hold_id": "HOLD-ERP-02002",
        "travel_date": "2026-09-03",
        "session_time": "09:00",
        "pickup_location": null,
        "dropoff_location": null,
        "selected_seats": ["4", "5"]
      }
    ]
  }
}

ERP processing:

1. Locate the hold by legacy_hold_id. Convert hold → confirmed booking.
2. Assign ticket codes (attraction products) from the ERP pool.
3. Emit a follow-up stock.updated with reason: b2c_booking_confirmed.
4. If e_ticket_delivery_method === "stock_upload" — call POST /api/v1/bridge/bookings/{platform_booking_id}/voucher with the pre-generated PDF URL(s). The marketplace will email them to the customer.
5. If legacy_hold_id is missing / expired / unknown → flag for manual ops review (do not silently drop).

payment.provider ∈ { "acetours_pay", "stripe", "fomopay" }; payment.reference is gateway-specific (e.g. pi_3Pxyz... for Stripe). See Payment Providers.

Event: booking.cancelled

{
  "event": "booking.cancelled",
  "platform_booking_id": "uuid-...",
  "booking_reference": "BK-2026-00123",
  "legacy_product_id": "PKG-001",
  "cancelled_at": "2026-05-13T08:00:00Z",
  "cancellation_reason": "Customer requested cancellation",
  "refund": { "amount": 2497.00, "currency": "SGD", "status": "refunded", "refunded_at": "2026-05-13T08:05:00Z" },
  "tax_summary": { "...": "see tax_summary below" }
}

ERP processing: release the stock for that booking, process refund allocation on the ERP side, emit stock.updated (release reason) to bump the mirror back up.

tax_summary — same structure every case, values differ

"tax_summary": {
  "destination_scope": "domestic",
  "tax_lines": [
    { "name": "GST (9%)",             "tax_type": "gst",      "rate": 0.09, "amount": "82.57", "inclusive": true  },
    { "name": "Batam Departure Levy", "tax_type": "port_tax", "rate": 0.00, "amount": "36.00", "inclusive": false }
  ],
  "embedded_tax_total": "82.57",
  "added_tax_total":    "36.00",
  "tax_total":          "118.57",
  "tax_note":           "Prices inclusive of 9% GST. Port levy collected on behalf of Batam Port Authority."
}

Reconciliation rules for the ERP:

• embedded_tax_total — inclusive tax already inside payment.amount. Does not add to the total.
• added_tax_total — exclusive port levy added on top. Already reflected in payment.amount.
• Port tax is never GST-taxed. The ERP must not apply GST to added_tax_total.

Idempotency & retry (marketplace → ERP)

• The marketplace retries failed deliveries: 1min → 5min → 15min → 1h → 4h, then dead-letters and alerts its admin.
• Each attempt has a fresh X-Webhook-Delivery-ID, but the same platform_booking_id + event.
• The ERP must dedupe on (platform_booking_id, event) — the marketplace does NOT suppress retries.
• Under load, the ERP responds 503 with Retry-After rather than timing out.

Pre-Uploaded Voucher Callback ERP → Marketplace

Booking · Surface 4 · stock_upload products only

For products with e_ticket_delivery_method: stock_upload, the ERP generates the tickets internally and pushes the PDF URL(s) to the marketplace via this callback. The marketplace stores the URLs and emails the PDFs to the customer as attachments.

Authentication

Same as all Bridge API calls — pass the bridge service key in X-Api-Key.

Request

Example request

POST /api/v1/bridge/bookings/0198f2b1-3b55-7c42-9b10-000000000301/voucher
X-Api-Key: <bridge-service-key>
Content-Type: application/json

{
  "vouchers": [
    { "url": "https://erp.example.com/tickets/BK-2026-01003-adult-1.pdf", "ticket_type": "adult" },
    { "url": "https://erp.example.com/tickets/BK-2026-01003-child-1.pdf", "ticket_type": "child" }
  ]
}

Responses

Idempotency

The callback is idempotent per booking. If voucher rows already exist for platform_booking_id, the request is a no-op and returns 200 already received. No duplicate rows are inserted and no additional email is sent.

Late callback flow

The marketplace dispatches the confirmation email after a configurable wait window (default 10 min) regardless of whether the ERP has called back. If the callback arrives after the email has already been sent:

1. Voucher rows are saved as normal.
2. The marketplace automatically dispatches a follow-up "Your voucher is ready" email with the PDF(s) attached.
3. The customer receives two emails total: the original confirmation (no PDFs) and the follow-up.

End-to-End Flow

Happy path from calendar view to confirmation. Steps 5–7 are identical for all payment providers.

Failure branches

Open Questions & Build Checklist

Open questions — decide with Marketplace / Architecture before building

Surface 1 — Stock Operations API (ERP hosts)

• GET /api/marketplace/stock/availability — per-date available + blackout
• POST /api/marketplace/stock/availability/batch — not yet built; per-unit availability check for multi-room/cabin bookings, see GET /stock/availability
• POST /api/marketplace/stock/holds — create hold, return hold_id, 409 on insufficient
• POST /api/marketplace/stock/holds/batch — not yet built; atomic multi-room/cabin hold, 409 with unavailable_units on partial conflict, see POST /stock/holds
• DELETE /api/marketplace/stock/holds/{hold_id} — idempotent release (hold_not_found = no-op)
• X-Api-Key auth on all five
• Respond within ~1s (marketplace timeout is 3s)
• Safety-net TTL auto-expiry on holds (Q5)

Surface 2 — Stock Sync Webhook (ERP emits)

• Emit stock.updated on every trigger in the triggers table (especially B2B movements)
• Correct HMAC signing: sha256= + hmac over {ts}.{raw_body}
• Unique event_id, accurate emitted_at
• Retry with backoff on non-2xx
• Initial backfill on product publish

Surface 3 — Booking Webhook receiver (ERP hosts)

• POST /api/marketplace/bookings accepting booking.confirmed + booking.cancelled
• Verify HMAC signature + 5-min replay window
• booking.confirmed: convert hold by legacy_hold_id, assign tickets, emit follow-up stock.updated
• booking.cancelled: release stock, process refund
• Dedupe on (platform_booking_id, event)
• Respond 202 within 10s; flag missing / expired legacy_hold_id for manual review
• If e_ticket_delivery_method === "stock_upload" — proceed to Surface 4

Surface 4 — Pre-Uploaded Voucher Callback (ERP calls Marketplace) — stock_upload only

• POST /api/v1/bridge/bookings/{platform_booking_id}/voucher with X-Api-Key
• One entry per ticket PDF: { url, ticket_type }
• Voucher count must equal pax.adults + pax.children — retry with corrected count on 422 voucher_count_mismatch
• Idempotent — 200 already received on duplicate calls
• Call as soon as PDFs are ready; the marketplace waits up to 10 min before sending the confirmation email
• Late callback (after email fires) triggers a follow-up "voucher ready" email automatically

Payment Providers — Three Options

Payment runs through one of three gateways. The booking flow (steps 5–7 in End-to-End Flow) is identical for all — only the integration details and the payment.provider value differ. Selectable per tenant / config.

Common contract the marketplace needs from any gateway

1. Create a payment for booking.total_amount (SGD) → return something the client can pay with (payment_url + token, or client_secret).
2. Verify a signed webhook on success → marketplace sets booking confirmed (atomic, amount-validated).
3. On failure → release hold via DELETE /stock/holds/{id}, booking payment_failed.

Regardless of provider, the ERP always receives the same booking.confirmed webhook; only payment.provider + payment.reference differ.

End-to-End Walkthrough

The full lifecycle, start to finish — every step links to the section that documents it. Four phases: Product Sync → Stock Sync → Booking → Payment.

Phase 1 — Product Sync ERP → Marketplace

1. Get credentials — request your Bridge service key (X-Api-Key) and the webhook HMAC secret (STOCK_WEBHOOK_SECRET) from EZCore. See Authentication.
2. Publish a product — POST /api/v1/bridge/products with the operator block, type, type_data, pricing[] and an initial availability[] seed. Expect 201 Created with b2c_visible: true. The type_data shape depends on type — see Product Types.
3. Verify it is live — GET /api/v1/bridge/products?legacy_product_id=... (or check the storefront) to confirm the product shows and stock seeded.
4. Update as needed — PUT /api/v1/bridge/products/{legacy-product-id} for price / detail changes (pricing[] is replaced as a full block).
5. Unpublish / delist — DELETE /api/v1/bridge/products/{legacy-product-id} for a reversible soft delist (unpublished) or permanent removal (delisted).

Phase 2 — Stock Sync ERP → Marketplace

1. Backfill on publish — right after first publish, emit a stock.updated for every active future date so the mirror matches the ERP.
2. Emit on every stock move — fire POST /api/marketplace/webhooks/stock on each trigger: b2b_booking_placed / b2b_booking_cancelled, b2c_hold_placed / b2c_hold_released, b2c_booking_confirmed, manual_allotment_change, blackout_toggled. Sign with HMAC-SHA256 over {timestamp}.{raw_body}; send a fresh event_id and current emitted_at. Expect 201 { "status": "processed" } (or 200 { "duplicate": true }).
3. Handle failures — on non-2xx, poll GET /webhooks/stock/events/{event_id}; if failed and retry_count < max_retry, re-send with the same event_id + emitted_at (fresh timestamp + signature). See Errors.

Phase 3 — Booking Marketplace → ERP

1. Customer browses — the marketplace reads the display-only mirror; no ERP call yet.
2. Check stock — at checkout the marketplace calls GET /stock/availability for a real-time count.
3. Place hold — POST /stock/holds with product_id, date, quantity, variant_code, session_time. 201 returns the ERP hold_id (stored as legacy_hold_id); 409 = insufficient stock and no booking is created. The ERP then emits stock.updated (b2c_hold_placed).
4. Booking record + payment session — the marketplace creates a pending_payment booking (15-min TTL) and a payment session, then returns a payment_url to the customer.

Phase 4 — Payment, Confirm & Cancel

1. Customer pays — via one of the three providers (acetours_pay / stripe / fomopay). The provider sends a signed result webhook to the marketplace, which verifies signature + amount.
2. Confirm — on success the marketplace sets the booking confirmed and sends the booking.confirmed webhook to the ERP (carrying legacy_hold_id, passengers[], payment, tax_summary). The ERP converts the hold to a booking by legacy_hold_id, assigns tickets, and emits stock.updated (b2c_booking_confirmed).
3. Payment failed / expiry — the marketplace releases the hold via DELETE /stock/holds/{hold_id} (idempotent). The 15-min cleanup job does the same on timeout; the ERP also enforces a safety-net TTL and emits stock.updated (b2c_hold_released).
4. Cancellation — after confirm, the marketplace sends booking.cancelled (with refund + tax_summary); the ERP releases stock, processes the refund, and emits stock.updated.
5. Reconciliation — run GET /api/v1/bridge/products?updated_after=<ts> nightly to catch any drift (e.g. admin-side status changes).

Auth & Config Summary

Every surface and its credentials in one place. All webhook signatures use HMAC-SHA256 over {timestamp}.{raw_body} (header X-Webhook-Signature: sha256=<hex> + X-Webhook-Timestamp), with a 300-second replay window — except Stripe and FOMO Pay, which use their own schemes.

Glossary

Every term, field, and code used across this guide.

Identity & Products

Pricing & Components

Stock & Availability

Booking & Holds

Payment & Tax

Webhooks, Auth & Ops

Open items — confirm with backend team before publishing

• Production ERP-facing base URL for Bridge + webhook routes.