Skip to content
Service Developers

The guarantee object

A guarantee is the card attached to a booking: what the guest agreed to, how much of it has been taken, and until when they can cancel without being charged. It arrives as the guarantee field on a reservation, and it has no endpoints of its own.

Fields

Section titled “Fields”

objectstring

Possible values: guarantee

The object type: always guarantee.

kindstring

Possible values: imprint prepayment

What the guest is guaranteeing with.

  • imprint: a saved card, charged only on a no-show or a late cancellation.
  • prepayment: payment up front. Reserved: no guarantee is issued with it today.

statestring

Possible values: awaiting_card active expired released charged partially_charged charge_failed refunded disputed withdrawn

Where the guarantee is in its own lifecycle, which is separate from the booking’s status.

  • awaiting_card: waiting for the guest to save a card, until expires_at.
  • active: a card is saved and can be charged under the terms the guest accepted.
  • expired: the guest did not save a card in time.
  • withdrawn: the restaurant withdrew the request before a card was saved.
  • released: the card was let go and nothing will be charged.
  • charged: the full amount was charged.
  • partially_charged: less than amount was charged.
  • charge_failed: a charge was attempted and declined; it may be retried.
  • refunded: money charged was refunded in full.
  • disputed: the guest disputed the charge with their bank.

originstring

Possible values: online_booking staff_request waitlist_offer

How the card was asked for.

  • online_booking: the guest saved it while booking in the restaurant’s widget.
  • staff_request: the guest was sent a link to save it — by the restaurant, or because the booking was created through this API.
  • waitlist_offer: the guest saves it to claim a place offered from the waitlist.

amountinteger

The most that can be charged, as the guest accepted it: in the minor unit of currency (cents), so 4000 is €40.00. Covers the whole party.

currencystring

ISO 4217 currency code of every amount on this object, e.g. EUR.

charged_amountinteger

How much has been charged so far, in minor units of currency. 0 when nothing has.

refunded_amountinteger

How much of charged_amount has been refunded, in minor units of currency. 0 when nothing has.

cardobjectnullable

null until the guest saves a card, and on a guarantee that never had one. Once a card is saved, its brand and the last four digits of its number; last4 can be null when the card network does not report it.

brandstring

The card network, as the payment processor reports it, e.g. visa.

last4stringnullable

The last four digits of the card number.

cancel_deadline_atstring (date-time)nullable

Until when the guest can cancel without being charged: ISO 8601 with the restaurant’s UTC offset. A cancellation after it may be charged. null means cancelling is always free and only a no-show is charged.

expires_atstring (date-time)nullable

While state is awaiting_card, the deadline for the guest to save a card, in the same format. null in every other state.

consented_atstring (date-time)optionalnullable

When the terms the guest accepts were recorded, in the same format: when the card was saved in the booking widget, or when the request was sent for a card asked for by link. null on a widget booking whose card is not saved yet.

created_atstring (date-time)

When the guarantee was created, in the same format.

updated_atstring (date-time)

When the guarantee last changed, in the same format.

Its lifecycle is not the booking’s

Section titled “Its lifecycle is not the booking’s”

state runs on its own track, separate from the booking’s status. The one place the two meet is awaiting_guarantee: a booking in that status is waiting for the guest to save a card, and its guarantee is awaiting_card until expires_at. The per-state meanings are in the field above.

Nothing here is yours to write

Section titled “Nothing here is yours to write”

There is no create, no update and no charge on this API. A guarantee appears because the restaurant’s rules asked for a card, or because a booking your key made landed on a slot that does, and it is charged, refunded or released outside this surface. Every amount is in the minor unit of currency and covers the whole party.

A change to a guarantee reaches you as a reservation.guarantee_* webhook, carrying the whole reservation with the guarantee on it.

Take a deposit walks a booking that asks the guest for a card.