Booking API

The Booking API gives you the same booking engine the widget and Fiko Pages use: services, free times that respect working hours, staff, existing bookings and your booking rules, and reservations that appear in the Fiko calendar, inbox and workflows. Use it to build your own booking screens, book from a mobile app or create bookings from your backend.

If you only need a booking form on a website, the booking widget does all of this with one script tag.

Base URL

https://api.fiko.net/api/v1/public/booking

Bodies are JSON. Send Content-Type: application/json on POST requests.

Keys

Create keys in Settings → API & Developers → Website booking & webhooks. Each key has a publishable and a secret part:

A key also sets how its bookings are confirmed (Request: pending until you approve, or Instant confirmation), whether an email address is required, and whether customers must pay on your website first.

Quick start

Book the first free time of a service in four calls:

KEY=pk_live_...
BASE=https://api.fiko.net/api/v1/public/booking

# 1. Services
curl -s "$BASE/services" -H "X-Fiko-Key: $KEY"

# 2. Days with free times in the next two weeks
curl -s "$BASE/availability/days?service_id=SERVICE_ID&days=14" -H "X-Fiko-Key: $KEY"

# 3. Free times on one day
curl -s "$BASE/availability?service_id=SERVICE_ID&date=2026-12-03" -H "X-Fiko-Key: $KEY"

# 4. Book
curl -s -X POST "$BASE/reservations" \
  -H "X-Fiko-Key: $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6c1f0a9e-checkout-1042" \
  -d '{
    "service_id": "SERVICE_ID",
    "date": "2026-12-03",
    "time": "14:30",
    "customer": { "name": "Ayşe Yılmaz", "phone": "+905551234567", "email": "ayse@example.com" },
    "notes": "First visit"
  }'

Business

The business's name, branding, time zone and booking rules, and the key's settings.

{
  "name": "Atelier Hair",
  "logo": "https://.../logo.png",
  "primary_color": "#0F766E",
  "timezone": "Europe/Istanbul",
  "phone": "+902121234567",
  "address": "Bağdat Cd. 120, Istanbul",
  "page_url": "https://fiko.io/atelier",
  "booking_window_days": 60,
  "same_day_booking": true,
  "min_cancel_hours": 12,
  "booking_mode": "request",
  "require_email": false
}

booking_window_days is how far ahead customers can book, min_cancel_hours how long before the start they can still cancel online.

List services

Bookable services in the order they are set up in Fiko, each with the staff (or rooms, tables…) that can do it.

{
  "object": "list",
  "data": [
    {
      "id": "3f2a6c1e-...",
      "name": "Haircut",
      "description": "Wash, cut and style",
      "duration_minutes": 45,
      "price": "650.00",
      "sale_price": null,
      "currency": "TRY",
      "image": "https://.../haircut.jpg",
      "color": "#0F766E",
      "resources": [
        { "id": "8d41e0a2-...", "name": "Elif", "type": "staff", "type_label": "Stylist" }
      ]
    }
  ]
}

Days with free times

For a month calendar: which days have at least one free time.

{
  "timezone": "Europe/Istanbul",
  "days": [
    { "date": "2026-12-01", "available": false },
    { "date": "2026-12-02", "available": true }
  ]
}

Results are cached for up to a minute; a day can fill up in between, so always load the times for the chosen day before booking.

Free times on a day

{
  "date": "2026-12-02",
  "timezone": "Europe/Istanbul",
  "slots": [
    { "time": "10:00", "start": "2026-12-02T07:00:00+00:00", "resource": { "id": "8d41e0a2-...", "name": "Elif" } },
    { "time": "10:30", "start": "2026-12-02T07:30:00+00:00", "resource": { "id": "b7c90f13-...", "name": "Can" } }
  ]
}

time is local to the business, start is UTC. Show time to customers and send it back when booking. Without resource_id, each time is offered with whoever is free.

Create a reservation

Send an Idempotency-Key header (any unique string up to 100 characters, such as a UUID or your order id) so a retried request never creates a second booking.

Returns 201 and the reservation. Its status is pending when the key is in Request mode and confirmed with Instant confirmation. The same request with the same Idempotency-Key within 24 hours returns 200 and the booking that was already made.

Bookings made with the publishable key are marked source: "website", with the secret key source: "api". The customer is added to (or matched in) your Fiko contacts by phone number.

Paid bookings

Take payment on your own website before a booking is made. Fiko never handles the money: you use your own payment provider (Stripe, iyzico, PayPal or any other), and Fiko keeps the time free for the customer while they pay.

1. The customer picks a service and a time on your website.
2. Your page creates a hold. The time is kept for 15 minutes (or what you ask for, 5 to 60), and nobody else can book it. Nothing is booked yet: no email, no webhook, nothing in the calendar.
3. You send the customer to your payment page. The hold tells you the price.
4. When the payment succeeds, your server confirms the hold with the secret key. That creates the reservation, with the usual emails and webhooks.
5. If the payment fails or the customer goes back, release the hold, or just let it expire.

Turn on Customers pay on my website first on the key. Then the publishable key can only create holds: POST /reservations from the browser returns 403 payment_required, so nobody can skip the payment by calling the API directly. Because the confirm step needs the secret key, only your server can turn a hold into a booking.

Create a hold

Takes the same fields as creating a reservation, plus:

Returns 201:

{
  "id": "6f0c2b7e-...",
  "object": "hold",
  "status": "held",
  "expires_at": "2026-12-01T11:45:00+00:00",
  "service": { "id": "3f2a6c1e-...", "name": "Haircut", "price": "750.00", "currency": "TRY" },
  "resource": { "id": "8d41e0a2-...", "name": "Elif" },
  "start": "2026-12-02T07:00:00+00:00",
  "end": "2026-12-02T07:45:00+00:00",
  "local_date": "2026-12-02",
  "local_time": "10:00",
  "timezone": "Europe/Istanbul",
  "business": { "name": "Atelier Hair" }
}

service.price is the sale price when the service has one. Put the hold id in your payment's metadata (for example Stripe's metadata.fiko_hold_id) so your server knows which hold to confirm. A 409 slot_unavailable means someone else got the time first: show the times again.

Confirm a hold

{ "payment_reference": "pi_3QxY...", "metadata": { "order_id": "1042" } }

Returns 201 and the reservation. Its status follows the key's mode; for paid bookings, Instant confirmation is usually what you want.

Confirming is safe to repeat: confirming the same hold again returns 200 and the same reservation, so you can retry after a timeout or when your payment provider sends its notification twice.

If the payment took longer than the hold, Fiko still books the time when it is free. If someone else booked it in the meantime you get 409 hold_expired: refund the customer or offer another time.

// Your Stripe webhook handler, after verifying Stripe's signature
if (event.type === "checkout.session.completed") {
  const session = event.data.object;
  const res = await fetch(
    `https://api.fiko.net/api/v1/public/booking/holds/${session.metadata.fiko_hold_id}/confirm`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.FIKO_SECRET_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ payment_reference: session.payment_intent }),
    },
  );
  if (res.status === 409) await refund(session.payment_intent); // the time was taken after the hold ran out
}

Check or release a hold

Returns the hold with status held or expired. Once confirmed it returns status: "confirmed" and the reservation, which is handy on your "thank you" page.

Gives the time back right away, for example when the payment fails or the customer cancels checkout. Returns status: "released".

List reservations

Newest start time first.

{ "object": "list", "has_more": false, "data": [ { "id": "...", "object": "reservation" } ] }

When has_more is true, narrow the date range to page through older bookings.

Get a reservation

Accepts the reservation id or the confirmation code customers see.

Cancel a reservation

{ "reason": "Customer called to cancel" }

Cancels as the business, so the customer cancellation deadline does not apply. Cancelling an already cancelled booking returns it unchanged. The customer is emailed and a booking.cancelled webhook is sent.

Customers cancel their own bookings with the manage_url link, within your deadline.

The reservation object

{
  "id": "a1b2c3d4-...",
  "object": "reservation",
  "confirmation_code": "K7Q2MD",
  "status": "confirmed",
  "service": { "id": "3f2a6c1e-...", "name": "Haircut" },
  "resource": { "id": "8d41e0a2-...", "name": "Elif" },
  "start": "2026-12-02T07:00:00+00:00",
  "end": "2026-12-02T07:45:00+00:00",
  "local_date": "2026-12-02",
  "local_time": "10:00",
  "timezone": "Europe/Istanbul",
  "business": { "name": "Atelier Hair" },
  "source": "website",
  "can_cancel": true,
  "created_at": "2026-11-20T18:04:11+00:00",
  "manage_url": "https://app.fiko.net/booking/manage/...",
  "google_calendar_url": "https://calendar.google.com/calendar/render?...",

  "customer": { "name": "Ayşe Yılmaz", "phone": "+905551234567", "email": "ayse@example.com" },
  "notes": "First visit",
  "metadata": { "order_id": "1042" }
}

customer, notes and metadata are only included for secret-key requests and in webhooks.

Errors

Errors use the common format.

Good practice

• Read times from /availability right before booking and handle 409 slot_unavailable by showing the times again.
• Always send an Idempotency-Key on POST /reservations, and reuse it when you retry.
• For paid bookings, confirm holds only from your server after the payment is verified, and keep the hold id with the payment.
• Treat pending as "requested": tell the customer the business will confirm, and listen for booking.confirmed in a webhook.
• Store the reservation id and keep it in sync with webhooks instead of polling the list.
• Show times in the business's time zone (local_time, timezone), not the visitor's.

Questions or something missing? Write to support@fiko.net.