Skip to main content

B2B API Glossary

Core concepts used throughout the B2B API and its documentation, defined in one place for partners, product teams, and AI coding agents alike.

Access Token​

A short-lived Bearer token issued by Auth0 once your app authenticates with its client credentials. Every request to the B2B API must carry it in the Authorization header. Tokens currently expire after 8600 seconds, so cache and reuse a token until shortly before it expires rather than requesting a new one for every call. See Authentication for the full flow.

Availability​

Whether a restaurant can be booked online for a given date, independent of any specific time. An Availability entry reports whether the restaurant still has at least one Timeslot available for that day and, if relevant, for which Offers. Availability is coarser than a Timeslot: it tells you a date is open, while a Timeslot tells you exactly which times are bookable and under what Guarantee Requirement.

It can be useful to present a calendar at the start of a reservation flow.

Customer​

The diner's profile as known in TheFork Manager: contact details, dietary restrictions and allergies, VIP status, reservation and spending history, communication opt-in and internal notes. A Customer is referenced by every Reservation and is scoped to a Restaurant Group, not to a single restaurant.

Double Booking​

This error occurs if the same diner attempts to book a reservation at the same restaurant (or another restaurant in the same group) within the same four-hour window as an existing reservation.

Guarantee Requirement​

The payment protection a restaurant can attach to a Timeslot or Offer to reduce no-shows — an amount, a minimum party size, and a minimum number of cancellation hours before it applies. A Guarantee Requirement is fulfilled through one of two mechanisms: an Imprint or a Prepayment.

Imprint (Credit Card Guarantee)​

In this scenario, the diner's card is saved but no funds are held or charged when the booking is made. If the diner no-shows, the restaurant can attempt to charge the card for the guarantee amount afterwards — a charge that can fail if funds aren't available at that point. Prepayment removes that risk by securing funds ahead of time. This option can be activated at restaurant level.

Meal Status​

Offers insight into which state the reservation is in at a given time — from arriving, to being seated, to receiving the bill, to leaving — reported on the Reservation as the restaurant's floor users update it. Unlike Reservation Status, these steps don't follow a fixed order and aren't guaranteed to all appear for a given visit.

Offer​

An offer is an umbrella term for either an experience at the restaurant (e.g. a 4-hands dinner, Karaoke Tuesday) or a special offer (e.g. 30% off the menu). Special offers aren't distributed via the API — they're restricted to TheFork Marketplace. Offers attach to Availability, Timeslot, and Reservation records.

Partner​

In the B2B API, a Partner is the external company — a CRM, a PMS, an AI phone bot — that authenticates and integrates against this API.

Party Size​

The number of guests on a Reservation — also referred to as "pax" or "covers" internally. It's both a field on every booking and a dimension restaurants can configure, since not every restaurant can accommodate every party size.

Prepayment​

Also called PPT. Restaurants can set a specific amount to be captured from the diner's card immediately when the booking is created. If the booking is cancelled within the allowed window, it's refunded automatically.

Reservation​

The central booking object in the B2B API: it links a Customer, a Party Size, a meal date and time, and a Reservation Status, plus optional Offer and Guarantee Requirement details. Nearly every part of the API either creates, reads, or updates a Reservation.

Reservation Status​

The lifecycle state of a Reservation: requested and awaiting confirmation, confirmed, refused, canceled, or marked as a no-show. Integrations should drive their own state off this field rather than inferring status from anything else, since it's the single source of truth for whether a booking is honored.

Restaurant Group​

A grouping of multiple restaurants under one partner account — typically a chain or a multi-location operator. Many parts of the B2B API let you filter Customers or Reservations across every restaurant in the group at once, instead of working restaurant by restaurant.

Restaurant UUID​

TheFork's unique identifier for a restaurant, used to reference it consistently across almost every part of the B2B API.

Review​

A diner's rating about a restaurant after a completed visit. It can be complemented with a written comment. It is tied to a Reservation, since TheFork only publishes reviews from diners who actually booked and attended. A restaurant can moderate incoming reviews and post a public reply.

Stock​

The restaurant's booking capacity for a specific day and time slot — whether there's room for another reservation. Stock is either attached to an Offer or to regular Availability (without an offer) — in this case, it's referred to as "normal stock."

Timeslot​

A specific bookable date and time at a restaurant, with its own Offers and Guarantee Requirement. Where Availability answers "is this date open at all," a Timeslot answers "can I book 7:30pm specifically, and under what conditions."

Webhook​

An event notification the B2B API pushes to a partner-configured URL whenever something changes — a Reservation created or updated, a Customer created, a Review rated. Partners must acknowledge receipt; unacknowledged events are retried. See Event & Webhook Flow for the full mechanics.