TapTime REST API

Every request needs a company API key (Integrations → Webhooks & API in the panel) sent as Authorization: Bearer tt_live_…. Responses and errors are JSON.

curl "https://api.tapti.me/v1/company/reservations?status=confirmed&updatedSince=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer tt_live_…"

Authentication

Every request carries a company API key as a bearer token. Create one from the panel — Integrations → Webhooks & API → REST API keys — where it is shown once and stored server-side only as a SHA-256 hash; a lost key is revoked and replaced, not recovered. A company can hold up to 10 active keys.

• Read-only keys can call every GET endpoint, and can subscribe and unsubscribe webhooks — a subscription pushes nothing the key could not already read.
• Read-write keys can also POST a booking status change; a read-only key gets 403 Forbidden on those routes.
• A key belongs to one company — every list and lookup is already scoped to it, there is no companyId parameter.

Rate limits

50 requests per minute per key, on a sliding window, shared by every endpoint. Going over returns 429 Too Many Requests; back off and retry rather than polling faster — or subscribe a webhook and stop polling.

Endpoints

The booking object

A reservation and an appointment come out in one shared shape: kind, id, status, source, guestInitiated, startsAt/endsAt/timezone (the branch's own zone), currency, company, branch, guest, attribution, conversionId, createdAt/updatedAt — plus partySize and table for a reservation, service and specialist for an appointment. It's exactly what a webhook delivers, so a receiver that handles one handles both.

{
  "data": {
    "kind": "reservation",
    "id": 4821,
    "status": "confirmed",
    "source": "online",
    "guestInitiated": true,
    "startsAt": "2026-09-12T20:00:00+03:00",
    "endsAt": "2026-09-12T21:30:00+03:00",
    "timezone": "Asia/Baku",
    "currency": "AZN",
    "company": { "id": 12, "name": "Cafe Aroma", "slug": "cafe-aroma", "country": "AZ" },
    "branch": { "id": 3, "name": "Nizami st." },
    "partySize": 4,
    "table": { "id": 9, "label": "T3" },
    "guest": { "name": "Maria K.", "phone": "…", "email": "…" },
    "locale": "en",
    "note": null,
    "conversionId": "tt3f9c…",
    "createdAt": "2026-09-10T08:12:04+00:00",
    "updatedAt": "2026-09-12T20:00:03+00:00",
    "attribution": { "channel": "widget", "utmSource": "instagram", "gclid": null, "fbclid": "IwAR2…" }
  }
}

The order object

An order comes out in one shape wherever you meet it — the REST API, the order webhooks, the event feed: kind ("order"), id, number (the ticket staff call out), status (open or paid), source (customer or staff), guestInitiated, fulfilment, table, label, deliveryAddress, note, currency, timezone, company, branch, customer (the loyalty member, when staff identified one), items (name, variant, quantity, unitPriceCents, subtotalCents), itemCount, subtotalCents, discountCents, deliveryFeeCents, tipCents, totalCents, valueCents (what the order is worth without the tip — the number conversions report), paymentMethod, servedBy, conversionId, createdAt, paidAt and attribution. Money is always in minor units.

{
  "data": {
    "kind": "order",
    "id": 9170,
    "number": 42,
    "status": "paid",
    "source": "customer",
    "guestInitiated": true,
    "fulfilment": "takeaway",
    "table": null,
    "label": "Ana",
    "currency": "EUR",
    "branch": { "id": 3, "name": "Vitosha Blvd" },
    "customer": { "id": 311, "name": "Ana", "phone": "…" },
    "items": [
      { "menuItemId": 88, "name": "Flat white", "variant": "Large",
        "quantity": 2, "unitPriceCents": 450, "subtotalCents": 900 }
    ],
    "itemCount": 2,
    "subtotalCents": 900,
    "discountCents": 0,
    "deliveryFeeCents": 0,
    "tipCents": 100,
    "totalCents": 1000,
    "valueCents": 900,
    "paymentMethod": "online",
    "conversionId": "tt81ad…",
    "createdAt": "2026-09-12T12:04:10+03:00",
    "paidAt": "2026-09-12T12:05:02+03:00",
    "attribution": { "channel": "web", "utmSource": "google", "gclid": "Cj0K…" }
  }
}

The loyalty object

Every loyalty event, card and reward shares one shape: kind ("loyalty"), id (the card), timezone, company, branch (where it happened, when there is one), program (id, name, stampsRequired, rewardTitle), customer (id, name, phone, locale), card (id, status, stampsCount, stampsRequired, stampsToReward, createdAt), stamp (for a stamp: source, issuedBy, createdAt) and reward (for a reward: code, title, status, expiresAt, redeemedAt, redeemedBy), plus conversionId, the id a loyalty sign-up is reported under.

{
  "kind": "loyalty",
  "id": 5120,
  "program": { "id": 4, "name": "Coffee card", "stampsRequired": 8, "rewardTitle": "Free coffee" },
  "customer": { "id": 311, "name": "Ana", "phone": "…", "locale": "bg" },
  "card": { "id": 5120, "status": "active", "stampsCount": 5,
            "stampsRequired": 8, "stampsToReward": 3 },
  "branch": { "id": 3, "name": "Vitosha Blvd" },
  "stamp": { "source": "qr_scan", "issuedBy": "Ivan", "createdAt": "…" },
  "reward": null,
  "conversionId": "tt5c02…"
}

Event feed

Each row is { id, cursor, type, createdAt, previousStatus, data }. data holds the subject under the key the event’s prefix names: data.booking, data.order or data.loyalty. Store the highest cursor you’ve processed and pass it back as after — it never skips or repeats a row, so it’s safe to resume after a crash. Ignore types you don’t handle: new ones may be added.

curl "https://api.tapti.me/v1/company/events?after=998&limit=100" \
  -H "Authorization: Bearer tt_live_…"

Webhooks

Create an endpoint under Integrations → Webhooks & API — or connect Zapier, Make, n8n or Pipedream under Integrations → Automation — to have TapTime POST a signed JSON event the moment a booking, an order or a loyalty card changes. You choose the events per endpoint. A company can have up to 50 webhooks, postbacks, chats and automation connections combined.

• Any 2xx response is treated as delivered; a non-2xx or a timeout is retried with backoff (1m, 5m, 15m, 1h, 3h, 6h, 12h) up to 8 attempts — a 410 stops retrying.
• Redirects are not followed.
• The URL must be HTTPS in production and may not point at a private or loopback address.
• Delivery is at-least-once: always verify the signature and dedupe on TapTime-Event-Id.

{
  "id": "evt_9f3c2a7e1b",
  "type": "booking.confirmed",
  "createdAt": "2026-09-12T19:02:11+03:00",
  "test": false,
  "data": { "booking": { "kind": "reservation", "id": 4821, "status": "confirmed", "…": "…" } }
}

const [t, v1] = req.headers["taptime-signature"]
  .split(",").map(part => part.split("=")[1]);
const expected = crypto
  .createHmac("sha256", process.env.TAPTIME_WEBHOOK_SECRET)
  .update(`${t}.${rawBody}`)
  .digest("hex");
const valid = crypto.timingSafeEqual(
  Buffer.from(expected), Buffer.from(v1));

Webhook subscriptions

Automation platforms switch triggers on and off through the API rather than asking the user to paste a URL (“REST hooks”): POST the platform’s own URL with the events it wants, keep the returned id, and DELETE it when the trigger is switched off. A subscription is an ordinary signed webhook — it shows in the panel, marked with the key that made it.

• A key sees and removes only the subscriptions it made; revoking the key removes them all.
• Addresses on hooks.zapier.com, make.com and pipedream.net are recognised and shown with the platform’s name; any other https address is a plain webhook.
• The signing secret is returned once, in the response to the POST; the owner can reveal it again in the panel.

curl -X POST "https://api.tapti.me/v1/company/webhooks" \
  -H "Authorization: Bearer tt_live_…" -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.zapier.com/hooks/catch/123/abc/", "events": ["order.placed"]}'

Postbacks

A GET or POST to your tracker’s own URL with macros filled in, for platforms that speak query-string postbacks rather than JSON webhooks. For an order, {value} is the order’s value without the tip and {order_id} its id.

https://tracker.example/postback
  ?cid={click_id}&event={event}&status={status}
  &payout={value}&cur={currency}

Available placeholders

• {event}
• {event_id}
• {status}
• {booking_id}
• {booking_type}
• {order_id}
• {customer_id}
• {conversion_id}
• {value}
• {currency}
• {party_size}
• {branch_id}
• {timestamp}
• {utm_source}
• {utm_medium}
• {utm_campaign}
• {utm_term}
• {utm_content}
• {gclid}
• {fbclid}
• {msclkid}
• {ttclid}
• {click_id}

Errors

Every error is JSON: { "error": "<code>", "message": "<human-readable>" }.