Joyal Booking API

-- PostgreSQL. Any database works: it is one optional text column.
alter table bookings add column joyal_ref text;

https://book.example.ie/sauna?joyal_ref=JY-AB23CD45XY

// On your booking page. Keep the code only if it is a real one.
const JOYAL_REF = /^JY-[A-HJKMNP-Z2-9]{10}$/

const ref = new URLSearchParams(window.location.search).get('joyal_ref')
if (ref && JOYAL_REF.test(ref)) {
  // Send it with the booking form, as a hidden field, so your server
  // stores it on the booking it creates.
  document.querySelector('input[name="joyal_ref"]').value = ref
}

• The format is always the same: JY- and 10 capital letters and numbers, 13 characters in all. I, L, O, 0 and 1 are never used. A value that does not match is not a Joyal code: leave the column empty.
• Joyal adds it only to https links on your booking site's own address, the one registered with your key (for example book.example.ie). Make sure the business's booking link in Joyal starts https:// and is on that address: any other link opens without a code.
• Store it exactly as it came, as text. It is different every time, and it is not a key for the business.
• Treat it as a label, nothing more. It comes from a link the customer can see, so never let it change a price or anything else in your system.
• On a test copy of your site only, also accept JY-TEST-PAID, JY-TEST-EXPIRED and JY-TEST-OTHER (step 7). A live key refuses them.

// Stripe Checkout, for example: metadata comes back on the
// checkout.session.completed event, so the code survives the trip.
const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  line_items: [{ price: priceId, quantity: 1 }],
  metadata: { booking_id: booking.id, joyal_ref: booking.joyal_ref ?? '' },
  success_url: 'https://book.example.ie/booked',
})

// Node.js 18 or later. The key lives on your server only.
const JOYAL_URL = 'https://joyal.co/api/v1/booking-events'

function bookingMessage(type, booking) {
  return {
    id: crypto.randomUUID(),            // new for each message, kept on retries
    type,                               // 'booking.created', 'booking.rescheduled' or 'booking.cancelled'
    occurred_at: new Date().toISOString(),
    booking: {
      id: String(booking.id),           // your id; it never changes
      joyal_ref: booking.joyal_ref,
      starts_at: booking.starts_at.toISOString(),
      ends_at: booking.ends_at.toISOString(),
      amount_paid: booking.amount_paid_cents, // 2500 is €25.00
      currency: 'EUR',
    },
  }
}

async function sendToJoyal(message) {
  const res = await fetch(JOYAL_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.JOYAL_BOOKING_KEY}`,
    },
    body: JSON.stringify(message),
    signal: AbortSignal.timeout(10000),
  })
  return { status: res.status, reply: await res.json().catch(() => null) }
}

// Where the payment is confirmed (Stripe: checkout.session.completed).
// queueForJoyal keeps it until it is sent (step 6).
if (booking.joyal_ref) {
  await queueForJoyal(bookingMessage('booking.created', booking), tx)
}

# Python 3, with the requests library
import os, requests

JOYAL_URL = "https://joyal.co/api/v1/booking-events"

def send_to_joyal(message):
    res = requests.post(
        JOYAL_URL,
        json=message,
        headers={"Authorization": f"Bearer {os.environ['JOYAL_BOOKING_KEY']}"},
        timeout=10,
    )
    return res.status_code, res.json() if res.content else None

• Only bookings that carry a joyal_ref. We do not want data on people who did not come through Joyal, and a message without one records nothing.
• Bookings only. Never send the purchase of a pass, package, gift voucher or membership. A session booked with one of them is a booking: send it, with the money actually taken for it, usually 0.
• One time slot per booking. If one checkout covers several slots, send each slot as its own booking, with its own id and its share of the amount. Several people in one slot is one booking.

// When the customer moves the booking to a new slot:
if (booking.joyal_ref) {
  await queueForJoyal(bookingMessage('booking.rescheduled', booking), tx)
}

// When it is cancelled, or refunded in full:
if (booking.joyal_ref) {
  await queueForJoyal(bookingMessage('booking.cancelled', booking), tx)
}

create table joyal_outbox (
  id          bigserial primary key,
  booking_id  text not null,
  message     jsonb not null,            -- exactly what bookingMessage() made
  attempts    int not null default 0,
  next_try_at timestamptz not null default now(),
  sent_at     timestamptz,
  failed_at   timestamptz                -- a 400 or 422: needs a person
);

// Called inside the same transaction that changes the booking, so the
// message is kept if, and only if, the change is.
async function queueForJoyal(message, tx) {
  await tx.query(
    'insert into joyal_outbox (booking_id, message) values ($1, $2)',
    [message.booking.id, message])
}

// Run every minute. One booking's messages go one at a time, in order.
async function sendWaitingMessages() {
  const due = await db.query(`
    select distinct on (booking_id) * from joyal_outbox
    where sent_at is null and failed_at is null
    order by booking_id, id`)
  for (const row of due.rows) {
    if (new Date(row.next_try_at) > new Date()) continue  // the oldest waits, so later ones wait too
    const { status, reply } = await sendToJoyal(row.message).catch(() => ({ status: 0 }))
    if (status >= 200 && status < 300) {
      await db.query('update joyal_outbox set sent_at = now() where id = $1', [row.id])
    } else if (status === 400 || status === 422) {
      await db.query('update joyal_outbox set failed_at = now() where id = $1', [row.id])
      console.error('Joyal refused a message', row.id, reply)  // fix it, then send it again
    } else {
      // 401, 429, 5xx or no answer: keep it and try later.
      const gaps = [1, 10, 60, 360]  // minutes, then every 6 hours
      const wait = gaps[Math.min(row.attempts, gaps.length - 1)]
      await db.query(
        `update joyal_outbox set attempts = attempts + 1,
           next_try_at = now() + make_interval(mins => $2) where id = $1`, [row.id, wait])
    }
  }
}

• In order, one at a time per booking. A move sent before its booking, or two moves the wrong way round, can leave the points at the wrong time.
• Keep the same message id on every retry. Joyal answers a repeat with the first reply and does nothing twice.
• Keep a 401 in the outbox. It means the key needs fixing, and once it is fixed the waiting messages go through, cancellations included.
• Give up after 3 days of trying, and tell a person.

curl https://joyal.co/api/v1/booking-events \
  -H "Authorization: Bearer $JOYAL_BOOKING_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "evt_test_1",
    "type": "booking.created",
    "occurred_at": "2026-10-22T11:03:00Z",
    "booking": {
      "id": "SW-48213",
      "joyal_ref": "JY-TEST-PAID",
      "starts_at": "2026-11-14T10:00:00Z",
      "ends_at": "2026-11-14T11:00:00Z",
      "amount_paid": 2500,
      "currency": "EUR"
    }
  }'

{
  "received": true,
  "mode": "test",
  "outcome": "matched",
  "points": 25,
  "credit_after": "2026-11-14T11:00:00.000Z",
  "detail": "Would add 25 points after 2026-11-14T11:00:00.000Z."
}

The points depend on the business's own rate: this one gives 1 point per euro. If the business has not switched points for bookings on yet, the outcome is switched_off, and the detail still says what would happen once it does. Send the same message again and you get the same outcome, marked as already received. Change something under the same id and you get a 422.

• Swap in the live key (jy_live_...), on your server only. Never in the booking page, an app or a link.
• Accept real codes only on your live booking page: the test codes are refused with a live key.
• Check the business's booking link in Joyal starts https:// and is on your booking site's address, so the code arrives on it.
• Send only bookings that carry a joyal_ref, once paid.
• Check your outbox sends each booking's messages in order, and alerts a person on a 400 or 422.
• Book one real session from the business's Joyal app, and check the customer sees their points on the way.