Skip to content

Keep your data in sync

For a new integration, use Sync orders, reservations and guests.

This guide copies guests, orders, reservations, refunds and disputes into your own CRM or data warehouse, using a venue key and the venue routes. You need one key per venue.

How it works

You keep a checkpoint per route. Each run asks for what changed since the checkpoint.

  1. Send your checkpoint as lastSyncedAt.
  2. We answer with the records, and a syncedAt time.
  3. Save the records. Update a record if you already have its id.
  4. Only then, save syncedAt as your new checkpoint for that route.

You keep the checkpoint. We do not store it for you. If you lose it, ask for the last 15 days again.

import os
import requests

BASE = "https://production.speakeasygo.com"
HEADERS = {"token": os.environ["SPEAKEASY_VENUE_TOKEN"]}

def sync_bookings(checkpoint, save):
    answer = requests.get(
        f"{BASE}/partners/sync/bookings",
        params={"lastSyncedAt": checkpoint},
        headers=HEADERS,
        timeout=120,
    )
    answer.raise_for_status()
    body = answer.json()
    for booking in body["bookings"]:
        save(booking)                # insert, or update by booking["id"]
    return body["syncedAt"]          # save this only after everything is stored

Routes and the order to call them

Route What it gives you Page
GET /partners/sync/users Guests of the venue Guests
GET /partners/sync/bookings Paid and free orders, with each ticket Orders
GET /partners/sync/reservations Table reservations and requests Reservations
GET /partners/sync/booking-refunds and booking-disputes Refunds and disputes on orders Refunds and disputes
GET /partners/sync/paylink-refunds and paylink-disputes Refunds and disputes on paylinks Refunds and disputes
GET /partners/sync/table-booking-refunds and table-booking-disputes Refunds and disputes on online table payments Refunds and disputes
GET /partners/sync/venue-users The venue's team Team members
GET /partners/events Event names and dates, to join by eventId Events

Call guests first, so that orders and reservations find their guest. Call one route at a time.

What the feeds cover, and what they do not

These limits are real. Plan for them.

  • Answers overlap. The lower time limit includes the checkpoint itself, and a record can come back on the next run. Always update by id, and never add a record twice.
  • A record can be in both lists of the same answer, such as newUsers and updatedUsers.
  • Orders are a feed of new orders only. sync/bookings picks orders by creation time and paymentStatus SUCCESS. A later refund or check-in does not bring an order back. Read the refund routes for that. The refundType on a ticket is current only at the time you read it.
  • Updated lists depend on the record's update time, and not every change moves it. A change to a paylink or a table payment does not by itself bring its reservation back. A check-in does not bring back its order. If you need to be sure about a record, read the refund and dispute routes.
  • Reservations include deleted rows. Look at isDeleted. On all other sync routes, deleted records simply stop coming back: nothing tells you they were removed.
  • There is no paging. A big venue can get a large answer, so use a long timeout.
  • Fields can be added at any time, because these routes return full records. Read only the fields you need, and do not fail on new ones.

If you fall behind

lastSyncedAt cannot be older than 15 days, except on venue-users. Older gets a 400, and the gap cannot be read through these routes. So run often enough that you never get near the limit, and alert yourself when a run fails.

To load history, or to close a gap, ask your Speakeasy contact for a one-time export.

Guest data

These routes return personal data. Store only the fields you use, and keep them safe.

Respect opt-outs. When venueHasCustomer.status is DISABLED, do not text this guest from your own tools: they opted out, or they never opted in. When optedEmailPolicy is DISABLED, the guest has not opted in to email.

A guest who replies STOP or START comes back in updatedUsers from November 5, 2026 on. Opt-outs from before then do not come back by themselves. If you text guests from your own tools, ask your Speakeasy contact for a one-time export, so that your list starts out right.