# Converted from Tock's published Swagger 2.0 model spec; schemas are verbatim from
# https://api.exploretock.com/docs/latest/reservation.swagger.json
openapi: 3.0.3
info:
title: Tock Reservation Model
version: '2.7'
description: >-
Data model for Tock reservations as published in the Tock API documentation (https://api.exploretock.com/docs/latest/reservation.html).
Reservation records are delivered to approved partners through the twice-daily Data Exports API and
the real-time Reservation Webhook; this specification documents the canonical reservation object and
all of its nested types. Access to the underlying API and webhook requires a Tock API key (request
from [email protected]) and a Premium or Premium Unlimited plan.
contact:
name: Tock Engineering
email: [email protected]
x-converted-from: swagger-2.0
x-source-url: https://api.exploretock.com/docs/latest/reservation.swagger.json
x-last-validated: '2026-06-03'
servers:
- url: https://api.exploretock.com
description: Tock API (partner access; API key required, Premium/Premium Unlimited plan)
paths: {}
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: >-
Tock-issued API key. Request access by emailing [email protected] from a Tock Dashboard Account
Owner; available on Premium and Premium Unlimited plans.
schemas:
protobufAny:
type: object
properties:
'@type':
type: string
additionalProperties: {}
rpcStatus:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
details:
type: array
items:
type: object
$ref: '#/components/schemas/protobufAny'
tockBusiness:
type: object
properties:
id:
type: string
format: uint64
description: A unique identifier for the business. Used internally by Tock.
name:
type: string
description: The name given to the business in the Tock Dashboard.
domainName:
type: string
description: >-
The unique section of exploretock.com that is devoted to showing inventory and allowing guests
to book reservations. The top-level URL will be of the form https://exploretock.com/{domainName}/.
locale:
type: string
description: >-
The locale that the business presents in using the ISO-3166 country code and ISO-639 language
code (e.g. en-us for US English, es-es for Spain Spanish).
currencyCode:
type: string
description: >-
The ISO 4217 three letter currency code that the business presents on exploretock.coms (e.g.
"USD" for US Dollar, "GBP" for Great Britain Pound).
timeZone:
type: string
description: >-
The time zone in which the business operates in the IANA named format (e.g. "America/Chicago").
tockDiscount:
type: object
properties:
description:
type: string
description: A textual description of the discount.
amountCents:
type: integer
format: int32
description: >-
The amount of the discount applied in some manner to the total price. This value will always
be a positive number.
discountType:
$ref: '#/components/schemas/tockDiscountDiscountType'
description: Where and how the discount is applied to the total price.
giftCard:
$ref: '#/components/schemas/tockGiftCard'
description: >-
If a gift card was used to apply the discount to the total price, this field will contain
extra information about the gift card used.
confirmationNumber:
type: string
description: >-
If a gift card was used to apply the discount to the total price, this field will contain
a confirmation number from the gift card provider that can be used to reconcile between Tock
and the provider.
promoCode:
type: string
description: >-
If the discount is applied through a promotional code, this field will be the short name of
promo code as configured in the Tock Dashboard.
ticketTypePromoCodeId:
type: string
format: uint64
description: >-
If the discount is applied through a promotional code, this field is a unique identifier assigned
to promotional code. Used internally by Tock.
loyaltyProgram:
$ref: '#/components/schemas/tockLoyaltyProgram'
description: >-
If the discount is for redeeming loyalty rewards program points, this field will contain extra
information about the loyalty program used.
tockDiscountDiscountType:
type: string
enum:
- CREDIT
- SUBTOTAL_COMP
- POST_TOTAL_ADMIN_COMP
- POST_TOTAL_REFUND
tockExperienceVariety:
type: string
enum:
- RESERVATION
- PREPAID
- DEPOSIT
- TABLESIDE
- PICKUP
- DELIVERY
- EVENT
tockGetReservationResponse:
type: object
properties:
reservation:
$ref: '#/components/schemas/tockReservation'
tockGiftCard:
type: object
properties:
giftCardProvider:
$ref: '#/components/schemas/tockGiftCardProviderType'
description: The provider of the gift card service for the business.
externalIdentifier:
type: string
description: The identifier of the card used for reconciliation with the gift card provider.
externalPin:
type: string
description: If provided, the security pin used to authenticate the owner of the gift card.
tockGiftCardProviderType:
type: string
enum:
- TCC
- STUB
- PAYTRONIX
tockKeyValue:
type: object
properties:
attribute:
type: string
description: The name of the metadata attribute.
attributeValue:
type: string
description: The value of the metadata attribute.
tockLoyaltyProgram:
type: object
properties:
providerType:
$ref: '#/components/schemas/tockLoyaltyProgramProviderType'
description: The loyalty program provider used when securing the reservation.
accountId:
type: string
description: >-
If known, the account identifier for the owner patron within the loyalty program.
tockLoyaltyProgramProviderType:
type: string
enum:
- PAYTRONIX
- ANNEXCLOUD
tockNote:
type: object
properties:
noteType:
$ref: '#/components/schemas/tockNoteNoteType'
description: The type of note being described by this object.
text:
type: string
description: The full text of the note.
tockNoteNoteType:
type: string
enum:
- BOOKING_GENERAL_NOTE
- BOOKING_DIETARY_NOTE
- GUEST_PROVIDED_NOTE
tockPartyState:
type: string
enum:
- EXPECTED
- ARRIVED
- SEATED
- LEFT
- NO_SHOW
- CANCELLED
- AWAITING_RESPONSE
- CONFIRMED_VIA_TEXT
- CONFIRMED_VIA_EMAIL
- PARTIALLY_ARRIVED
- PARTIALLY_SEATED
- FINISHED
tockPatron:
type: object
properties:
id:
type: string
format: uint64
description: A unique identifier assigned to the patron. Used internally by Tock.
email:
type: string
description: >-
The email address of the patron. No two patrons can have the same email address, but an email
address is not required of all patrons.
firstName:
type: string
description: If known, the first name of the patron.
lastName:
type: string
description: If known, the last name of the patron.
phone:
type: string
description: If known, the phone number of the patron without the country code.
phoneCountryCode:
type: string
description: >-
If known, the country code for the patron using the prefix code and the ISO 3166-1 alpha-2
country code (e.g. "+1 US").
zipCode:
type: string
description: If known, the zip code given by the patron in their Tock profile.
imageUrl:
type: string
description: If known, a URL to a public image of the patron.
isoCountryCode:
type: string
description: If known, the ISO 3166-1 alpha-2 country code where the patron lives.
loyaltyProgramCardNumber:
type: string
description: >-
If known and if the business participates in an integrated loyalty program, this field contains
the card number given to the patron by the business.
loyaltyProgramAccountId:
type: string
description: >-
If known and if the business participates in an integrated loyalty program, this field contains
the account identifier given to the patron by the business.
tockPaymentType:
type: string
enum:
- NONE
- CREDIT_CARD
- CHASE_PAY
- CHASE_ULTIMATE_REWARDS
- TOCK_GIFT_CARD
- PAY_ON_SITE
tockPayout:
type: object
properties:
id:
type: string
format: int64
description: A unique identifier assigned to the payout. Used internally by Tock.
arrivalDate:
type: string
description: >-
The date that this payout is expected to arrive in the business bank account pending any potential
rejections by the bank.
tockPurchasedCustomCharge:
type: object
properties:
name:
type: string
description: >-
The name given to the custom charge when created on the reservation in the Tock Dashboard.
amountCents:
type: string
format: uint64
description: The amount added to the total price for this custom charge.
tockPurchasedExperience:
type: object
properties:
id:
type: string
format: uint64
description: A unique identifier for the experience. Used internally by Tock.
name:
type: string
description: >-
The name given to the experience which is displayed prominently when booking or within the
Tock Dashboard.
amountCents:
type: string
format: uint64
description: >-
The amount added to the total price for the experience and does not contain any values associated
with add-on(s) or menu item(s).
posSku:
type: string
description: >-
If assigned by the business from the Tock Dashboard, this field will be the SKU denoting the
experience.
variety:
$ref: '#/components/schemas/tockExperienceVariety'
description: The type of experience being offered by the business.
tockPurchasedFee:
type: object
properties:
id:
type: string
format: uint64
description: A unique identifier for the fee. Used internally by Tock.
name:
type: string
description: The name assigned in the Tock Dashboard to this additional fee.
amountCents:
type: string
format: uint64
description: The amount added to the total price for this additional fee.
posSku:
type: string
description: >-
If assigned by the business from the Tock Dashboard, this field will be the SKU denoting the
fee.
tockPurchasedOption:
type: object
properties:
id:
type: string
format: uint64
description: A unique identifier for the option. Used internally by Tock.
name:
type: string
description: The name assigned in the Tock Dashboard to this optional item.
amountCents:
type: string
format: uint64
description: >-
The amount added to the total price for just this one option purchased along with the experience.
posSku:
type: string
description: >-
If assigned by the business from the Tock Dashboard, this field will be the SKU denoting the
option.
tockQuestion:
type: object
properties:
name:
type: string
description: The short name of this question assigned in the Tock Dashboard.
response:
type: array
items:
type: string
description: >-
All responses to the question. If the guest was presented with checkboxes to answer the question
there may be multiple responses listed through this field.
tockRating:
type: string
enum:
- BAD
- NEUTRAL
- GOOD
tockRatingType:
type: string
enum:
- THREE_POINT_EMOTICON
- FIVE_POINT_STAR
tockRefund:
type: object
properties:
id:
type: string
format: int64
description: A unique identifier assigned to the refund. Used internally by Tock.
amount:
type: integer
format: int32
description: >-
The amount of the original payment that was refunded. This value will always be a positive
number.
isDispute:
type: boolean
description: >-
This field indicates whether this refund was issued because of a lost chargeback dispute.
status:
$ref: '#/components/schemas/tockRefundRefundStatus'
description: >-
The current status of the refund within the payment processor that serviced the original payment.
payout:
$ref: '#/components/schemas/tockPayout'
description: >-
The Tock-generated payout that includes this refund as a debit to the business bank account.
If the business connects to Tock for payment processing using Stripe this field will not be
present.
processorId:
type: string
description: >-
A unique identifier assigned to the refund by the payment processor indicated by the paymentType.
processorFeeRefundedCents:
type: integer
format: int64
description: >-
The amount the of the payment processor fee that was returned as a result of the refund.
tockFeeRefundedCents:
type: integer
format: int64
description: The amount of the Tock fee that was returned as a result of the refund.
tockRefundRefundStatus:
type: string
enum:
- COMPLETE
- DEFERRED
- ERROR
tockReservation:
type: object
properties:
id:
type: string
format: uint64
description: >-
A unique identifier for the reservation. This identifier will not change no matter what edits
have been made to the reservation. Transferred reservations will get new unique identifiers
and are considered new reservations.
business:
$ref: '#/components/schemas/tockBusiness'
description: >-
Details about the business this reservation is for; useful for business groups that have multiple
businesses supported by Tock.
dateTime:
type: string
description: >-
The start time of the reservation in the business time zone of the form HH:MM using the 24
hour clock and excluding seconds (e.g. 4:15pm would have a dateTime of "16:15").
partySize:
type: integer
format: int32
description: The size of the party on the reservation.
experience:
$ref: '#/components/schemas/tockPurchasedExperience'
description: >-
The experience assigned to the reservation in Tock. This is present even if no money is attached
to the reservation and will not be present for walk-ins.
option:
type: array
items:
type: object
$ref: '#/components/schemas/tockPurchasedOption'
description: >-
Any add-on(s) or menu item(s) that has been booked along with this reservation. This is present
even if no money is attached to this option and will not be present for walk-ins.
fee:
type: array
items:
type: object
$ref: '#/components/schemas/tockPurchasedFee'
description: >-
Any fee(s) charged automatically to the party as part of the reservation. This does not include
any custom fees applied to the reservation from the Tock Dashboard.
customCharge:
type: array
items:
type: object
$ref: '#/components/schemas/tockPurchasedCustomCharge'
description: >-
Any custom charges charged to the party as part of the reservation through the Tock Dashboard.
keyValue:
type: array
items:
type: object
$ref: '#/components/schemas/tockKeyValue'
description: >-
Any metadata associated with this reservation collected during the checkout process. Examples
of potential metadata are UTM tracking parameters indicating how the guest originally came
to make the reservation.
compAmountCents:
type: integer
format: int32
description: >-
The total amount of all complimentary discounts applied through the Tock Dashboard to a paid
reservation.
subtotalCents:
type: integer
format: int32
description: The subtotal given on the receipt for the reservation.
taxRate:
type: number
format: float
description: >-
If tax has been applied to the subtotal and not for individual purchased items, this is the
tax rate applied to the subtotal. If using multiple tax rates for individual items, this field
will not be present.
taxCents:
type: integer
format: int32
description: The total amount of tax collected for the reservation.
serviceChargeRate:
type: number
format: float
description: >-
If a service charge has been applied to the reservation, this field is the rate applied to
the subtotal.
serviceChargeCents:
type: integer
format: int32
description: >-
If a service charge has been applied to the reservation, this field is the amount of service
charge added to the total price.
selectedGratuityRate:
type: number
format: float
description: >-
If gratuity has been added to the reservation by the party through choosing a fixed percentage,
this field is the gratuity rate selected and applied to the subtotal. If a custom gratuity
was chosen manually, this field will be zero.
gratuityCents:
type: integer
format: int32
description: >-
The gratuity applied by the party to the reservation and added to the total price.
eventFeeRate:
type: number
format: float
description: >-
For reservations to events where a fee is applied, the event fee rate applied to the subtotal.
eventFeeCents:
type: integer
format: int32
description: >-
For reservations to events where a fee is applied, the total amount of that fee added to the
total price.
customFeeRate:
type: number
format: float
description: >-
If applied to the reservation from the Tock Dashboard, this field contains the custom fee
rate applied to the subtotal and added to the total price.
customFeeCents:
type: integer
format: int32
description: >-
If applied to the reservation from the Tock Dashboard, this field contains the custom fee
amount applied to the subtotal and added to the total price.
customFeeName:
type: string
description: >-
If applied to the reservation from the Tock Dashboard, this field contains the name of the
custom fee applied to the total price.
totalPriceCents:
type: integer
format: int32
description: The total price of the reservation including all fees, charges, taxes.
discount:
type: array
items:
type: object
$ref: '#/components/schemas/tockDiscount'
description: >-
Any discounts applied to the total price of the reservation, either automatically during checkout
or through application in the Tock Dashboard. This does not include complimentary discounts
applied to the reservation (see compAmountCents for that value).
netAmountPaidCents:
type: integer
format: int32
description: >-
The amount that has been charged to the party for this reservation. Does not need to be the
same as the total price of the reservation.
amountDueCents:
type: integer
format: int32
description: >-
The amount that is still due to cover the total price of the reservation. This will be the
totalPriceCents field less the netAmountPaidCents field.
createdTimestamp:
type: string
format: uint64
description: >-
The timestamp for when this reservation was first created, in milliseconds since the Unix
Epoch.
lastUpdatedTimestamp:
type: string
format: uint64
description: >-
The timestamp for the last modification to this reservation, in milliseconds since the Unix
Epoch.
serviceDateTimestamp:
type: string
format: uint64
description: >-
The timestamp for the start time of the reservation, in milliseconds since the Unix Epoch.
This is a convenience field as it does not require the business timezone.
transferredOut:
type: boolean
description: Whether the reservation has been transferred to a different party.
transferredOutAmountCents:
type: integer
format: int64
description: >-
If this reservation has been transferred to a different party, the amount the original owner
charged the transferee for the reservation.
isCancelled:
type: boolean
description: >-
Whether this reservation has been marked as cancelled, either by the user or through the Tock
Dashboard. No modifications can happen to a reservation after it is cancelled.
ownerPatron:
$ref: '#/components/schemas/tockPatron'
description: >-
The "owner" patron is the one who initiated payment for the reservation. It is most commonly
the same as the "diner" patron unless it booked through a concierge or altered directly from
the Tock Dashboard.
dinerPatron:
$ref: '#/components/schemas/tockPatron'
description: >-
The patron whose name will appear on the reservation in the Tock Dashboard. Is is most commonly
the same as the ownerPatron unless booked through a concierge or altered directly from the
Tock Dashboard.
versionId:
type: string
format: uint64
description: >-
A version identifier used by Tock to indicate how many edits have been made to the original
reservation. This is for Tock internal use only and a better indication of the number of edits
is in the sequenceId field.
loyaltyProgramCardNumberUsed:
type: string
description: >-
If the reservation was made by a patron that has linked their loyalty program account, this
field contains the unique number used to identify the loyalty card used.
visitFeedback:
type: array
items:
type: object
$ref: '#/components/schemas/tockVisitFeedback'
description: >-
The results of answering any questions about the reservation after the party has visited.
visitTag:
type: array
items:
type: object
$ref: '#/components/schemas/tockVisitTag'
description: >-
Any tags applied to the reservation in the Tock Dashboard specific to this reservation and
not to the guest as a whole.
payment:
type: array
items:
type: object
$ref: '#/components/schemas/tockTockPayment'
description: >-
All payments made to secure this reservation. Payments take many forms (credit cards, gift
cards, reward points, etc.) and the type of payment used is indicated inside the nested objects.
refund:
type: array
items:
type: object
$ref: '#/components/schemas/tockRefund'
description: >-
Any refunds applied to any payments made on this reservation. Refunds are applied in the Tock
Dashboard through edits to the reservation or applying any form of discount. These refunds
are applied to the original form(s) of payment to secure the reservation.
partyState:
$ref: '#/components/schemas/tockPartyState'
description: The current state of the party within the Tock Dashboard.
sequenceId:
type: integer
format: int64
description: >-
An identifier that starts at zero and increases by one for each edit to the reservation. Use
this field to denote that the reservation has changed since the previous sequenceId.
confirmationCode:
type: string
description: >-
The reservation confirmation code given to the party. Currently always eight characters. This
field is not set for walk-ins.
serverName:
type: string
description: >-
The employees names used to serve the party for the reservation. If multiple employees were
assigned, they will be delimited with the word "and" (e.g. Luci and Dezi).
walkinId:
type: string
format: int64
description: Used only for encoding walk-in data, maps to the visit id
note:
type: array
items:
type: object
$ref: '#/components/schemas/tockNote'
description: >-
A note that has been attached to this reservation or guest through actions in the Tock Dashboard.
Imported reservations may also have notes.
question:
type: array
items:
type: object
$ref: '#/components/schemas/tockQuestion'
description: >-
Any questions answered by the party about this reservation prior to the service date.
table:
type: array
items:
type: object
$ref: '#/components/schemas/tockTable'
description: Table(s) assigned to the reservation sorted alphabetically by ascending order.
seatingOption:
$ref: '#/components/schemas/tockSeatingOption'
description: An area of the floor plan (also known as seating area)
tockSeatingOption:
type: object
properties:
id:
type: string
format: int64
description: A unique identifier for the seating option. Used internally by Tock.
name:
type: string
description: >-
The name given to the seating option which is displayed within the Tock Dashboard.
isOutdoors:
type: boolean
description: This field indicates whether or not the seating option is outdoors.
tockTable:
type: object
properties:
id:
type: string
format: uint64
description: A unique identifier. Used internally by Tock.
name:
type: string
description: The name of the table.
room:
type: string
description: The room the table resides in.
externalId:
type: string
description: ID used by external integrations
tockTockPayment:
type: object
properties:
id:
type: string
format: int64
description: A unique identifier assigned to the payment. Used internally by Tock.
amount:
type: integer
format: int32
description: The amount of the reservation that was paid using the paymentType.
payout:
$ref: '#/components/schemas/tockPayout'
description: >-
The Tock-generated payout that includes this payment as a credit to the business bank account.
If the business connects to Tock for payment processing using Stripe this field will not be
present.
paymentType:
$ref: '#/components/schemas/tockPaymentType'
description: The form of payment used for this portion of total price on the reservation.
processorId:
type: string
description: >-
A unique identifier assigned to the payment by the payment processor indicated by the paymentType.
processorFeeCents:
type: integer
format: int64
description: The amount the payment processor kept from the payment to perform the service.
tockFeeCents:
type: integer
format: int64
description: The fee that Tock kept from the payment to perform the service.
tockVisitFeedback:
type: object
properties:
id:
type: string
format: uint64
description: A unique identifier for this feedback. Used internally by Tock.
rating:
$ref: '#/components/schemas/tockRating'
description: The rating supplied by the guest indicating their opinion about the experience.
message:
type: string
description: A custom message included with the feedback from the guest.
isLocked:
type: boolean
description: >-
Feedback can be altered until a message is given along with the rating. This indicates whether
the feedback has been locked with a message and is unable to be altered again.
createdAtEpochSec:
type: string
format: int64
description: >-
The timestamp for when the feedback was submitted by the guest, in seconds from the Unix Epoch.
ratingType:
$ref: '#/components/schemas/tockRatingType'
description: The rating scale of feedback request
ratingScore:
type: integer
format: int64
description: The rating supplied by the guest indicating their opinion about the experience.
tockVisitTag:
type: object
properties:
tag:
type: string
description: The name of the tag assigned to the reservation.