> ## 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.

# Bookings

> Create, confirm, and cancel bookings via the Reseller API.

The booking flow for resellers is three steps: create a booking attempt, receive payment
from your customer, then confirm it with Seyaha by posting the external payment ID.

## Booking status lifecycle

```
Booking Attempt  →  (payment received)  →  Paid by Customer  →  (cancelled)  →  Cancelled
```

## Create a booking

```
POST /api/v1/resellers/add-booking
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.seyaha.net/api/v1/resellers/add-booking \
    -H "x-api-token: $RESELLER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "activity_id": "6744810075becd2ef8c140f7",
      "variation_id": "6751ad2d7533f379c9a1711b",
      "customer_details": {
        "name": "Jane Smith",
        "email": "jane@example.com",
        "phone": "+966501234567"
      },
      "booking_details": {
        "booking_date": "2026-07-15",
        "booking_time": "10:00",
        "currency": "USD",
        "guests": { "adult": 2, "child": 1, "infant": 0 },
        "pickup_address": {
          "address": "Riyadh Marriott Hotel",
          "lat": 24.6877,
          "lng": 46.7219
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch('https://api.seyaha.net/api/v1/resellers/add-booking', {
    method: 'POST',
    headers: {
      'x-api-token': process.env.RESELLER_TOKEN,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      activity_id: activityId,
      variation_id: varId,
      customer_details: {
        name: 'Jane Smith',
        email: 'jane@example.com',
        phone: '+966501234567',
      },
      booking_details: {
        booking_date: '2026-07-15',
        booking_time: '10:00',
        currency: 'USD',
        guests: { adult: 2, child: 1, infant: 0 },
      },
    }),
  });
  const { data: booking } = await res.json();
  // booking.status === 'Booking Attempt'
  // Save booking._id for the payment-success call
  ```
</CodeGroup>

The response booking has `status: "Booking Attempt"`. The slot is reserved but not
confirmed until payment is posted.

***

## Confirm after payment

Once your payment gateway confirms payment, post the external payment ID to convert
the booking to `Paid by Customer`:

```
POST /api/v1/resellers/payment-success
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.seyaha.net/api/v1/resellers/payment-success \
    -H "x-api-token: $RESELLER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "booking_id": "67c896a6639e6ff76dd2f882",
      "external_payment_id": "pay_1N9dvSLkdIwHu2QOxgMtN9dE"
    }'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch('https://api.seyaha.net/api/v1/resellers/payment-success', {
    method: 'POST',
    headers: {
      'x-api-token': process.env.RESELLER_TOKEN,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      booking_id: bookingId,
      external_payment_id: paymentGatewayId,
    }),
  });
  const { data: confirmedBooking } = await res.json();
  // confirmedBooking.status === 'Paid by Customer'
  ```
</CodeGroup>

***

## Cancel a booking

<Warning>
  Cancellation processes a refund according to the activity's cancellation policy.
  Only bookings with status `Paid by Customer` can be cancelled. Cancellation is
  irreversible — there is no undo endpoint.
</Warning>

```
POST /api/v1/resellers/bookings/cancel-booking
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.seyaha.net/api/v1/resellers/bookings/cancel-booking \
    -H "Authorization: Bearer $RESELLER_JWT" \
    -H "Content-Type: application/json" \
    -d '{ "booking_id": "67c896a6639e6ff76dd2f882" }'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch(
    'https://api.seyaha.net/api/v1/resellers/bookings/cancel-booking',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${resellerJwt}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ booking_id: bookingId }),
    }
  );
  ```
</CodeGroup>

***

## Look up bookings for a user

```
GET /api/v1/resellers/users/bookings/{user_id}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.seyaha.net/api/v1/resellers/users/bookings/$USER_ID?page=1&pageSize=10" \
    -H "x-api-token: $RESELLER_TOKEN"
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({ page: '1', pageSize: '10' });
  const res = await fetch(
    `https://api.seyaha.net/api/v1/resellers/users/bookings/${userId}?${params}`,
    { headers: { 'x-api-token': process.env.RESELLER_TOKEN } }
  );
  ```
</CodeGroup>

## Booking object reference

| Field                 | Description                                             |
| --------------------- | ------------------------------------------------------- |
| `_id`                 | Booking ID                                              |
| `status`              | `Booking Attempt` / `Paid by Customer` / `Cancelled`    |
| `partnerConfirmation` | `Pending` / `Confirmed` / `Rejected` / `Not Required`   |
| `bookingDate`         | Date of the activity (`YYYY-MM-DD`)                     |
| `bookingTime`         | Time of the activity (`HH:mm`)                          |
| `price.totalPrice`    | Total amount charged                                    |
| `external_payment_id` | Payment gateway reference (set after `payment-success`) |