For the complete documentation index, see llms.txt.

Paid Bookings

Collect payments via Stripe before confirming bookings on your Venn Links.

Overview

Vennio uses Stripe Connect (Express accounts) with direct charges to let your users accept payments on their booking links. When a Venn Link has a price, customers are redirected to Stripe Checkout before the booking is confirmed. Once payment succeeds, Vennio automatically confirms the booking, creates the calendar event, and sends confirmation emails.

Setup

Three steps to enable paid bookings for a user:

1. Connect Stripe

Create a Stripe Express connected account for the user:

curl -X POST https://api.vennio.app/v1/stripe/connect \
  -H "Authorization: Bearer vennio_sk_live_YOUR_KEY"

{
  "stripe_account_id": "acct_1234567890",
  "onboarding_complete": false,
  "charges_enabled": false,
  "ready": false
}

This endpoint is idempotent — calling it again returns the existing account.

2. Complete onboarding

Generate an account session for the embedded onboarding UI. Use the client_secret with Stripe's Connect embedded components:

curl -X POST https://api.vennio.app/v1/stripe/account-session \
  -H "Authorization: Bearer vennio_sk_live_YOUR_KEY"

{
  "client_secret": "acss_xxxxxxxxxxxxx"
}

3. Verify readiness

Check that onboarding is complete and the account can accept charges:

curl https://api.vennio.app/v1/stripe/account \
  -H "Authorization: Bearer vennio_sk_live_YOUR_KEY"

{
  "stripe_account_id": "acct_1234567890",
  "charges_enabled": true,
  "payouts_enabled": true,
  "details_submitted": true,
  "onboarding_complete": true,
  "ready": true
}
ready flag

The ready field is true when both charges_enabled and onboarding_complete are true. Only accounts with ready: true can accept paid bookings.

Add pricing to a Venn Link

Set price_amount (in cents) and price_currency (ISO 4217) on a Venn Link to make it paid:

curl -X POST https://api.vennio.app/v1/venn-links \
  -H "Authorization: Bearer vennio_sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Strategy Session",
    "event_type_id": "YOUR_EVENT_TYPE_ID",
    "price_amount": 5000,
    "price_currency": "usd"
  }'
Value Meaning
null Inherit pricing from the event type (default)
0 Explicitly free — no payment required
> 0 Paid — amount in cents (e.g. 5000 = $50.00)

Paid booking flow

When a customer books a paid Venn Link, the flow is:

  1. Customer submits booking via POST /v1/venn-links/:shortCode/book
  2. Vennio creates the booking with status pending_payment
  3. Vennio creates a Stripe Checkout session and returns a checkout_url
  4. Customer completes payment on Stripe Checkout
  5. Stripe sends checkout.session.completed webhook to Vennio
  6. Vennio confirms the booking, creates the calendar event, and sends confirmation emails
# Book a paid Venn Link
curl -X POST https://api.vennio.app/v1/venn-links/abc123/book \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email": "customer@example.com",
    "customer_name": "Jane Doe",
    "start_time": "2026-03-15T10:00:00Z",
    "end_time": "2026-03-15T10:30:00Z"
  }'

{
  "success": true,
  "booking": {
    "id": "booking_xyz789",
    "status": "pending_payment",
    "start_time": "2026-03-15T10:00:00Z",
    "end_time": "2026-03-15T10:30:00Z",
    "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_..."
  },
  "message": "Booking created. Redirect customer to checkout_url to complete payment."
}
Redirect required

The booking is not confirmed until the customer completes payment. Redirect them to the checkout_url immediately after receiving the response.

You can optionally pass success_url and cancel_url to override the default Stripe Checkout redirect destinations.

Booking questions

Define custom form fields on an event type or Venn Link. Customers submit answers when booking, and answers are included in confirmation emails.

Define questions

Add a booking_questions array when creating or updating an event type or Venn Link:

{
  "booking_questions": [
    {
      "type": "text",
      "label": "Company name",
      "required": true,
      "placeholder": "Acme Corp"
    },
    {
      "type": "select",
      "label": "Meeting topic",
      "required": true,
      "options": ["Product demo", "Technical support", "Partnership"]
    },
    {
      "type": "textarea",
      "label": "Anything else?",
      "required": false
    }
  ]
}

Supported question types:

Type Description Extra fields
text Single-line text input placeholder
textarea Multi-line text input placeholder
select Dropdown selection options (required, 1-50 strings)
checkbox Boolean checkbox default_value
phone Phone number input placeholder
email Email address input placeholder

Each question receives a stable id (e.g. q_a3f8b2c1) generated by the server. Use these IDs to key answers when booking.

Submit answers

Pass an answers object keyed by question ID when booking:

{
  "customer_email": "customer@example.com",
  "customer_name": "Jane Doe",
  "start_time": "2026-03-15T10:00:00Z",
  "end_time": "2026-03-15T10:30:00Z",
  "answers": {
    "q_a3f8b2c1": "Acme Corp",
    "q_b7e2d4f0": "Product demo",
    "q_c9f1a3e5": "Looking forward to learning more!"
  }
}

Testing

Use demo_mode: true on booking requests to skip calendar events, emails, and webhooks. For payment testing, use Stripe test mode API keys — Stripe provides test card numbers for simulating successful and failed payments.

Limitations