Skip to main content
POST
/
api
/
b2a
/
execute_booking
Execute Booking
curl --request POST \
  --url https://api.privetag.com/api/b2a/execute_booking \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "activity_id": "<string>",
  "user_email": "<string>",
  "user_name": "<string>",
  "booking_date": "<string>",
  "num_adults": 123,
  "num_children": 123,
  "context_log_id": "<string>",
  "special_requests": "<string>",
  "webhook_url": "<string>"
}
'
{
  "success": true,
  "data": {
    "booking_id": "<string>",
    "status": "<string>",
    "voucher": {
      "code": "<string>",
      "qr_url": "<string>",
      "valid_until": "<string>"
    },
    "activity": {
      "id": "<string>",
      "title": "<string>",
      "location": "<string>",
      "check_in_instructions": "<string>"
    },
    "pricing": {
      "unit_price": 123,
      "total_guests": 123,
      "subtotal": 123,
      "discount": 123,
      "total": 123,
      "currency": "<string>"
    },
    "email_sent": true,
    "email_sent_at": "<string>"
  }
}

​
Execute Booking

This endpoint creates a real booking and sends a voucher email within 30 seconds. 99% success rate with live inventory sync.

​
Use This Endpoint When

User confirms selection

  • “Book this one”
  • “Reserve for tomorrow”
  • “I want the spa package”

After recommendation

  • User selected from /recommend results
  • User chose from /inventory listings

​
Request

​
activity_id
string
required
Activity ID from /recommend or /inventory response
​
user_email
string
required
Email address for voucher delivery
​
user_name
string
required
Guest name for the voucher
​
booking_date
string
required
ISO 8601 date format (e.g., 2025-12-15)
​
num_adults
number
required
Number of adults (1-20)
​
num_children
number
default:"0"
Number of children
​
context_log_id
string
Recommended: Pass the log_id from /recommend response for conversion tracking and feedback loop
​
special_requests
string
Any special requests or notes
​
webhook_url
string
Optional URL to receive booking status callbacks

​
Response

​
success
boolean
Whether the booking was created successfully
​
data
object

​
Examples

​
Basic Booking

curl -X POST https://api.privetag.com/api/b2a/execute_booking \
  -H "x-api-key: pk_a1b2c3..." \
  -H "Content-Type: application/json" \
  -d '{
    "activity_id": "act_abc123",
    "user_email": "guest@example.com",
    "user_name": "John Doe",
    "booking_date": "2025-12-15",
    "num_adults": 2,
    "context_log_id": "ctx_xyz789"
  }'

​
Family Booking with Children

{
  "activity_id": "act_abc123",
  "user_email": "family@example.com",
  "user_name": "Smith Family",
  "booking_date": "2025-12-20",
  "num_adults": 2,
  "num_children": 3,
  "special_requests": "One child is under 3 years old",
  "context_log_id": "ctx_xyz789"
}

​
With Webhook Callback

{
  "activity_id": "act_abc123",
  "user_email": "guest@example.com",
  "user_name": "John Doe",
  "booking_date": "2025-12-15",
  "num_adults": 2,
  "webhook_url": "https://your-server.com/webhooks/privetag"
}

​
Response Example

{
  "success": true,
  "data": {
    "booking_id": "bkg_h7j9k2m4",
    "status": "confirmed",
    "voucher": {
      "code": "PVT-2025-ABC123",
      "qr_url": "https://cdn.privetag.com/vouchers/qr/bkg_h7j9k2m4.png",
      "valid_until": "2025-12-15T23:59:59Z"
    },
    "activity": {
      "id": "act_abc123",
      "title": "Safari World Bangkok",
      "location": "99 Panyaintra Road, Sam Wa Tawan Tok, Bangkok",
      "check_in_instructions": "Show QR code at main entrance ticket counter"
    },
    "pricing": {
      "unit_price": 1500,
      "total_guests": 2,
      "subtotal": 3000,
      "discount": 0,
      "total": 3000,
      "currency": "THB"
    },
    "email_sent": true,
    "email_sent_at": "2025-12-10T14:30:15Z"
  }
}

​
Booking Flow

​
Ground Truth Feedback Loop

Why pass context_log_id?When a user visits the venue and scans their QR code, we connect:
  1. The original recommendation context
  2. Which activity was booked
  3. Whether they actually visited
This creates a feedback loop that improves future recommendations for similar user profiles.

​
Webhook Events

If you provide a webhook_url, you’ll receive callbacks for:
EventDescription
booking_confirmedBooking successfully created
voucher_deliveredEmail sent to user
qr_verifiedUser visited venue (Ground Truth)
booking_cancelledBooking was cancelled
Webhook payload example: 
{
  "event": "qr_verified",
  "booking_id": "bkg_h7j9k2m4",
  "activity_id": "act_abc123",
  "verified_at": "2025-12-15T10:30:00Z",
  "context_log_id": "ctx_xyz789"
}

​
Error Responses

CodeDescription
ACTIVITY_NOT_FOUNDActivity ID doesn’t exist
ACTIVITY_UNAVAILABLEActivity not available on requested date
INVALID_DATEBooking date is in the past or too far ahead
INVENTORY_EXHAUSTEDNo more slots available
INVALID_EMAILEmail format is invalid
BOOKING_LIMIT_EXCEEDEDMaximum guests per booking exceeded

​
Error Response Example

{
  "success": false,
  "error": "Activity not available",
  "code": "ACTIVITY_UNAVAILABLE",
  "details": "Safari World is closed on Mondays. Available dates: Tue-Sun"
}

​
Best Practices

This enables the Ground Truth feedback loop, improving recommendations over time.
Use webhooks to update your UI in real-time when voucher is delivered or QR is scanned.
Check that booking_date is not in the past and is within the activity’s operating days.
Bookings are real and charged. Always confirm details with the user before calling this endpoint.

​
Next Steps

Check Inventory

View real-time availability before booking

Webhooks

Set up webhook callbacks for booking events