> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seyaha.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Sync & Booking Lifecycle

> How Seyaha calls your API during catalog sync and the booking lifecycle.

## Catalog sync flow

Seyaha syncs your catalog on a nightly schedule and whenever a sync is manually triggered.
Here is the sequence of calls your API will receive during a sync:

```
Seyaha                                 Your API
  │                                        │
  │── GET /products?updated_since=... ───▶ │
  │◀─ 200 [ OctoProduct, ... ] ──────────── │
  │                                        │
  │ (for each product × option)            │
  │── POST /availability ────────────────▶ │
  │    { productId, optionId,              │
  │      localDateStart, localDateEnd,     │
  │      units: [{ id: "unit-adult", q:1}]}│
  │◀─ 200 [ OctoAvailability, ... ] ─────── │
  │                                        │
  │ (upserts activities + slots in DB)     │
```

Seyaha syncs availability **60 days ahead** from today. On the next sync, it passes
`updated_since` set to the previous `last_sync_at` timestamp — return only changed
products to keep the sync fast.

## Health probes

In addition to syncs, Seyaha probes your `GET /products?limit=1` endpoint periodically
to verify connectivity. Your endpoint must return `200` quickly (default timeout: 5 seconds)
to stay HEALTHY. You can return an empty array or a single product — the content is not
used during probes.

## Booking lifecycle

When a customer on Seyaha books one of your activities:

```
Customer      Seyaha                            Your API
   │             │                                  │
   │ checkout ──▶│── POST /availability ──────────▶ │
   │             │◀─ [ slots ] ─────────────────── │
   │             │                                  │
   │             │── POST /bookings/reserve ───────▶│
   │             │◀─ { reservationCode, expiresAt } │
   │             │                                  │
   │ pays ──────▶│── POST /bookings/confirm ───────▶│
   │             │◀─ { externalBookingId, tickets } │
   │             │                                  │
   │ (confirmed) │                                  │
```

### On checkout

Seyaha calls `POST /availability` for the specific date to get a fresh `availabilityId`
if the locally cached one is stale, then calls `POST /bookings/reserve` to hold the slot.

### On payment

After a successful payment Seyaha calls `POST /bookings/confirm` with the
`reservationConfirmationCode` from the reserve step.

### On hold expiry / abandonment

If the customer does not complete payment before `expiresAt`, Seyaha calls
`DELETE /bookings/{reservationCode}` to release the hold. Your endpoint should
free the slot so other customers can book it.

### On cancellation

When a paid booking is cancelled, Seyaha calls
`POST /bookings/{externalBookingId}/cancel`. Implement this if you want cancellations
to propagate to your platform.

## Timeouts

Seyaha applies the following timeouts when calling your API:

| Endpoint                       | Timeout                         | Notes                          |
| ------------------------------ | ------------------------------- | ------------------------------ |
| `GET /products` (health probe) | 5 s                             | Degraded integrations get 10 s |
| `GET /products` (sync)         | 15 s                            |                                |
| `POST /availability`           | 20 s                            |                                |
| `POST /bookings/reserve`       | 5 s (HEALTHY) / 10 s (DEGRADED) |                                |
| `POST /bookings/confirm`       | 5 s (HEALTHY) / 10 s (DEGRADED) |                                |
| `DELETE /bookings/{code}`      | 10 s                            |                                |
| `POST /bookings/{id}/cancel`   | 10 s                            |                                |

Design your endpoints to respond well within these limits, especially `/availability`
which is called on every option of every product during a full sync.