You are viewing a non-production environment — the API surface may differ from production.
Developers
Booking API

Bookings

Table reservations and booking management

List bookings

GET
/api/v1/bookings

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Query Parameters

locationId?number

Filter by location ID

tableId?string

Filter by table ID

status?string

Booking status

Value in

  • "pending"
  • "confirmed"
  • "checked_in"
  • "seated"
  • "completed"
  • "cancelled"
  • "no_show"
bookingDate?string

Filter by exact date

Formatdate
startDate?string

Filter by start date (inclusive)

Formatdate
endDate?string

Filter by end date (inclusive)

Formatdate
userId?number

Filter by user ID

confirmationCode?string

Filter by confirmation code

bookingSource?string

Source of the booking

Value in

  • "direct"
  • "website"
  • "app"
  • "phone"
  • "walkin"
  • "third_party"
guestEmail?string

Filter by guest contact email (case-insensitive). Finds bookings made without a user account, which have no userId to filter on.

guestPhone?string

Filter by guest contact phone (exact match). Finds bookings made without a user account, which have no userId to filter on.

page?number

Page number

Range1 <= value
Default1
limit?number

Items per page

Range1 <= value <= 100
Default50

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/bookings"
{  "status": "success",  "data": {    "bookings": [      {        "customFields": [          {            "fieldId": "string",            "key": "string",            "label": "string",            "group": "string",            "type": "string",            "displayValue": "string",            "value": null,            "version": 0,            "status": "string"          }        ],        "metadata": {          "customFields": {}        },        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "locationId": 0,        "tableId": "073fbfcb-cd05-4203-be18-a1ce6f8e4d2d",        "bookingDate": "2019-08-24",        "startTime": "string",        "endTime": "string",        "timezone": "string",        "primaryUserId": null,        "guestCount": 0,        "occasion": "none",        "specialRequests": "string",        "internalNotes": "string",        "notes": [          {            "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",            "note": "string",            "sortOrder": 0,            "createdByRetailerUserId": 0,            "updatedByRetailerUserId": 0,            "createdAt": "2019-08-24T14:15:22Z",            "updatedAt": "2019-08-24T14:15:22Z"          }        ],        "status": "pending",        "paymentType": "none",        "depositAmountCents": 0,        "purchaseId": 0,        "confirmationCode": "string",        "bookingSource": "direct",        "estimatedRevenueCents": 0,        "guestName": "string",        "guestEmail": "string",        "guestPhone": "string",        "createdAt": "2019-08-24T14:15:22Z",        "updatedAt": "2019-08-24T14:15:22Z",        "confirmedAt": "2019-08-24T14:15:22Z",        "seatedAt": "2019-08-24T14:15:22Z",        "completedAt": "2019-08-24T14:15:22Z",        "cancelledAt": "2019-08-24T14:15:22Z",        "tabId": "string",        "defaultTabStrategy": "single",        "resources": [          {            "qrCodeId": "8a619d64-dbe8-4c9d-9490-babe22a53a28",            "isPrimary": true,            "position": 0          }        ],        "userName": "string",        "userEmail": "string",        "userPhone": "string",        "tableName": "string",        "location": {          "id": 0,          "name": "string",          "city": "string",          "latitude": 0,          "longitude": 0,          "logoImageUrl": "string"        },        "attribution": {          "firstTouch": {            "capturedAt": "2019-08-24T14:15:22Z",            "utmSource": "string",            "utmMedium": "string",            "utmCampaign": "string",            "utmContent": "string",            "utmTerm": "string",            "referrer": "string",            "landingPage": "string"          },          "bookingTouch": {            "capturedAt": "2019-08-24T14:15:22Z",            "utmSource": "string",            "utmMedium": "string",            "utmCampaign": "string",            "utmContent": "string",            "utmTerm": "string",            "referrer": "string",            "landingPage": "string"          },          "reportedSource": "string",          "recordedAt": "2019-08-24T14:15:22Z"        }      }    ],    "pagination": {      "page": 1,      "limit": 1,      "total": 0,      "totalPages": 0    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Create booking

POST
/api/v1/bookings

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

guestFieldAnswers?unknown

Guest form schema token and answers; validated against the current reservation form.

customFields?array<|>

Optional custom field operations, saved atomically with this record. Omitted values are unchanged; null clears. Use fieldId or a stable key. expectedVersion is optional; supply it to reject conflicting edits.

Itemsitems <= 100
requiredItemAnswers?unknown

Guest form answers keyed by the booking group's required item ID.

locationId*number

Location ID

tableId?|

Legacy single-resource ID (kept for backwards compat). When tableIds is provided it takes precedence; otherwise tableId is folded into a single-element resource set.

Formatuuid
tableIds?array<>

Multi-resource booking (Phase 40). Array of storefront_qr_code UUIDs to reserve. The first entry is treated as primary. When provided, supersedes tableId.

Items1 <= items
defaultTabStrategy?string

Tab strategy locked in at booking time (Phase 40). single (default) — one shared tab across all reserved resources. per_resource — one tab per resource opened on seat.

Default"single"

Value in

  • "single"
  • "per_resource"
bookingDate*string

Date of the booking

Formatdate
startTime*string

Start time (HH:MM)

endTime*string

End time (HH:MM)

timezone*string

Timezone (e.g., Europe/Stockholm)

primaryUserId?|

Primary guest user ID (null for walk-ins)

guestCount*number

Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests)

Range0 <= value
occasion?string

Occasion for the booking

Value in

  • "none"
  • "birthday"
  • "anniversary"
  • "business"
  • "date"
  • "celebration"
  • "other"
specialRequests?string

Guest special requests

internalNotes?string

Staff-only notes

paymentType?string

Payment type required for booking

Value in

  • "none"
  • "deposit"
  • "full_prepayment"
depositAmountCents?number

Deposit amount in cents

bookingSource?string

Source of the booking

Value in

  • "direct"
  • "website"
  • "app"
  • "phone"
  • "walkin"
  • "third_party"
guestName?string

Guest contact name

guestEmail?string

Guest contact email

guestPhone?string

Guest contact phone

seatImmediately?boolean

If true, immediately seat the booking after creation. Requires a table assignment. Will check for conflicting open tabs on the table.

sendNotification?boolean

Whether to send the guest a confirmation by email and SMS when the new booking is already confirmed. Defaults to true. This does not suppress booking webhooks or internal events.

Defaulttrue
sendConfirmation?boolean
Deprecated

Deprecated alias for sendNotification. An explicit false still suppresses the guest confirmation for backwards compatibility.

attribution?

Optional, client-reported first-touch and booking-touch attribution. Saved once at creation; booking channel is separate. URLs are stripped of query, fragment and credentials. No custom-field entitlement is needed.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/bookings" \  -H "Content-Type: application/json" \  -d '{    "locationId": 0,    "bookingDate": "2019-08-24",    "startTime": "string",    "endTime": "string",    "timezone": "string",    "guestCount": 0  }'
{  "status": "success",  "data": {    "customFields": [      {        "fieldId": "string",        "key": "string",        "label": "string",        "group": "string",        "type": "string",        "displayValue": "string",        "value": null,        "version": 0,        "status": "string"      }    ],    "metadata": {      "customFields": {}    },    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "locationId": 0,    "tableId": "073fbfcb-cd05-4203-be18-a1ce6f8e4d2d",    "bookingDate": "2019-08-24",    "startTime": "string",    "endTime": "string",    "timezone": "string",    "primaryUserId": null,    "guestCount": 0,    "occasion": "none",    "specialRequests": "string",    "internalNotes": "string",    "notes": [      {        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",        "note": "string",        "sortOrder": 0,        "createdByRetailerUserId": 0,        "updatedByRetailerUserId": 0,        "createdAt": "2019-08-24T14:15:22Z",        "updatedAt": "2019-08-24T14:15:22Z"      }    ],    "status": "pending",    "paymentType": "none",    "depositAmountCents": 0,    "purchaseId": 0,    "confirmationCode": "string",    "bookingSource": "direct",    "estimatedRevenueCents": 0,    "guestName": "string",    "guestEmail": "string",    "guestPhone": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "confirmedAt": "2019-08-24T14:15:22Z",    "seatedAt": "2019-08-24T14:15:22Z",    "completedAt": "2019-08-24T14:15:22Z",    "cancelledAt": "2019-08-24T14:15:22Z",    "tabId": "string",    "defaultTabStrategy": "single",    "resources": [      {        "qrCodeId": "8a619d64-dbe8-4c9d-9490-babe22a53a28",        "isPrimary": true,        "position": 0      }    ],    "userName": "string",    "userEmail": "string",    "userPhone": "string",    "tableName": "string",    "location": {      "id": 0,      "name": "string",      "city": "string",      "latitude": 0,      "longitude": 0,      "logoImageUrl": "string"    },    "tab": {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "tabMemberId": "eacdba71-5d30-4031-bb4d-d05e652a7917"    },    "requiresPayment": true,    "totalRequiredItemsCents": 0,    "confirmationDelivery": {      "email": "sent",      "sms": "sent"    },    "seated": true,    "seatWarning": "string",    "attribution": {      "firstTouch": {        "capturedAt": "2019-08-24T14:15:22Z",        "utmSource": "string",        "utmMedium": "string",        "utmCampaign": "string",        "utmContent": "string",        "utmTerm": "string",        "referrer": "string",        "landingPage": "string"      },      "bookingTouch": {        "capturedAt": "2019-08-24T14:15:22Z",        "utmSource": "string",        "utmMedium": "string",        "utmCampaign": "string",        "utmContent": "string",        "utmTerm": "string",        "referrer": "string",        "landingPage": "string"      },      "reportedSource": "string",      "recordedAt": "2019-08-24T14:15:22Z"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Get booking

GET
/api/v1/bookings/{id}

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Booking ID

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/bookings/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "status": "success",  "data": {    "customFields": [      {        "fieldId": "string",        "key": "string",        "label": "string",        "group": "string",        "type": "string",        "displayValue": "string",        "value": null,        "version": 0,        "status": "string"      }    ],    "metadata": {      "customFields": {}    },    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "locationId": 0,    "tableId": "073fbfcb-cd05-4203-be18-a1ce6f8e4d2d",    "bookingDate": "2019-08-24",    "startTime": "string",    "endTime": "string",    "timezone": "string",    "primaryUserId": null,    "guestCount": 0,    "occasion": "none",    "specialRequests": "string",    "internalNotes": "string",    "notes": [      {        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",        "note": "string",        "sortOrder": 0,        "createdByRetailerUserId": 0,        "updatedByRetailerUserId": 0,        "createdAt": "2019-08-24T14:15:22Z",        "updatedAt": "2019-08-24T14:15:22Z"      }    ],    "status": "pending",    "paymentType": "none",    "depositAmountCents": 0,    "purchaseId": 0,    "confirmationCode": "string",    "bookingSource": "direct",    "estimatedRevenueCents": 0,    "guestName": "string",    "guestEmail": "string",    "guestPhone": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "confirmedAt": "2019-08-24T14:15:22Z",    "seatedAt": "2019-08-24T14:15:22Z",    "completedAt": "2019-08-24T14:15:22Z",    "cancelledAt": "2019-08-24T14:15:22Z",    "tabId": "string",    "defaultTabStrategy": "single",    "resources": [      {        "qrCodeId": "8a619d64-dbe8-4c9d-9490-babe22a53a28",        "isPrimary": true,        "position": 0      }    ],    "userName": "string",    "userEmail": "string",    "userPhone": "string",    "tableName": "string",    "location": {      "id": 0,      "name": "string",      "city": "string",      "latitude": 0,      "longitude": 0,      "logoImageUrl": "string"    },    "attribution": {      "firstTouch": {        "capturedAt": "2019-08-24T14:15:22Z",        "utmSource": "string",        "utmMedium": "string",        "utmCampaign": "string",        "utmContent": "string",        "utmTerm": "string",        "referrer": "string",        "landingPage": "string"      },      "bookingTouch": {        "capturedAt": "2019-08-24T14:15:22Z",        "utmSource": "string",        "utmMedium": "string",        "utmCampaign": "string",        "utmContent": "string",        "utmTerm": "string",        "referrer": "string",        "landingPage": "string"      },      "reportedSource": "string",      "recordedAt": "2019-08-24T14:15:22Z"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Update booking

PUT
/api/v1/bookings/{id}

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Booking ID

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

tableId?|

Legacy single-resource ID (kept for backwards compatibility). When tableIds is provided it takes precedence; otherwise tableId replaces the booking resource set with a single entry and moves the booking's pre-arrival or started tab to that table. Set null to unassign.

Formatuuid
tableIds?array<>

Multi-resource booking (Phase 40). Array of storefront_qr_code UUIDs that replaces the booking resource set. The first entry is treated as primary. When provided, supersedes tableId.

Items1 <= items
defaultTabStrategy?string

Change the booking tab strategy pre-seat (Phase 40). Staff can flip between single and per_resource until the booking is seated.

Value in

  • "single"
  • "per_resource"
confirmRemoveActiveTab?boolean

Applies only to multi-resource tableIds updates. When shrinking the resource set would remove a table currently serving guests, the API proceeds only if this flag is true. Without it, the update returns 409 ACTIVE_TAB_ON_REMOVED_RESOURCE. Pre-arrival and settled tabs do not require confirmation.

Defaultfalse
bookingDate?string

Date of the booking

Formatdate
startTime?string

Start time

endTime?string

End time

guestCount?number

Number of guests (0 allowed for walk-ins where staff opens a tab for drinks-only / non-food guests)

Range0 <= value
occasion?string

Occasion for the booking

Value in

  • "none"
  • "birthday"
  • "anniversary"
  • "business"
  • "date"
  • "celebration"
  • "other"
specialRequests?string

Guest special requests

internalNotes?string

Staff-only notes

paymentType?string

Payment type required for booking

Value in

  • "none"
  • "deposit"
  • "full_prepayment"
depositAmountCents?number

Deposit amount in cents

customFields?array<|>

Optional custom field operations, saved atomically with this record. Omitted values are unchanged; null clears. Use fieldId or a stable key. expectedVersion is optional; supply it to reject conflicting edits.

Itemsitems <= 100

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/api/v1/bookings/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'
{  "status": "success",  "data": {    "customFields": [      {        "fieldId": "string",        "key": "string",        "label": "string",        "group": "string",        "type": "string",        "displayValue": "string",        "value": null,        "version": 0,        "status": "string"      }    ],    "metadata": {      "customFields": {}    },    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "locationId": 0,    "tableId": "073fbfcb-cd05-4203-be18-a1ce6f8e4d2d",    "bookingDate": "2019-08-24",    "startTime": "string",    "endTime": "string",    "timezone": "string",    "primaryUserId": null,    "guestCount": 0,    "occasion": "none",    "specialRequests": "string",    "internalNotes": "string",    "notes": [      {        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",        "note": "string",        "sortOrder": 0,        "createdByRetailerUserId": 0,        "updatedByRetailerUserId": 0,        "createdAt": "2019-08-24T14:15:22Z",        "updatedAt": "2019-08-24T14:15:22Z"      }    ],    "status": "pending",    "paymentType": "none",    "depositAmountCents": 0,    "purchaseId": 0,    "confirmationCode": "string",    "bookingSource": "direct",    "estimatedRevenueCents": 0,    "guestName": "string",    "guestEmail": "string",    "guestPhone": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "confirmedAt": "2019-08-24T14:15:22Z",    "seatedAt": "2019-08-24T14:15:22Z",    "completedAt": "2019-08-24T14:15:22Z",    "cancelledAt": "2019-08-24T14:15:22Z",    "tabId": "string",    "defaultTabStrategy": "single",    "resources": [      {        "qrCodeId": "8a619d64-dbe8-4c9d-9490-babe22a53a28",        "isPrimary": true,        "position": 0      }    ],    "userName": "string",    "userEmail": "string",    "userPhone": "string",    "tableName": "string",    "location": {      "id": 0,      "name": "string",      "city": "string",      "latitude": 0,      "longitude": 0,      "logoImageUrl": "string"    },    "attribution": {      "firstTouch": {        "capturedAt": "2019-08-24T14:15:22Z",        "utmSource": "string",        "utmMedium": "string",        "utmCampaign": "string",        "utmContent": "string",        "utmTerm": "string",        "referrer": "string",        "landingPage": "string"      },      "bookingTouch": {        "capturedAt": "2019-08-24T14:15:22Z",        "utmSource": "string",        "utmMedium": "string",        "utmCampaign": "string",        "utmContent": "string",        "utmTerm": "string",        "referrer": "string",        "landingPage": "string"      },      "reportedSource": "string",      "recordedAt": "2019-08-24T14:15:22Z"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Cancel booking

POST
/api/v1/bookings/{id}/cancel

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Booking ID

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

reason?string

Cancellation reason

closeTab?boolean

Whether to close the linked pre-arrival tab. Defaults to true.

sendNotification?boolean

Whether to send the guest a cancellation by email and SMS. Defaults to true. This does not suppress booking webhooks or internal events.

Defaulttrue

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/bookings/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel" \  -H "Content-Type: application/json" \  -d '{}'
{  "status": "success",  "data": {    "customFields": [      {        "fieldId": "string",        "key": "string",        "label": "string",        "group": "string",        "type": "string",        "displayValue": "string",        "value": null,        "version": 0,        "status": "string"      }    ],    "metadata": {      "customFields": {}    },    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "locationId": 0,    "tableId": "073fbfcb-cd05-4203-be18-a1ce6f8e4d2d",    "bookingDate": "2019-08-24",    "startTime": "string",    "endTime": "string",    "timezone": "string",    "primaryUserId": null,    "guestCount": 0,    "occasion": "none",    "specialRequests": "string",    "internalNotes": "string",    "notes": [      {        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",        "note": "string",        "sortOrder": 0,        "createdByRetailerUserId": 0,        "updatedByRetailerUserId": 0,        "createdAt": "2019-08-24T14:15:22Z",        "updatedAt": "2019-08-24T14:15:22Z"      }    ],    "status": "pending",    "paymentType": "none",    "depositAmountCents": 0,    "purchaseId": 0,    "confirmationCode": "string",    "bookingSource": "direct",    "estimatedRevenueCents": 0,    "guestName": "string",    "guestEmail": "string",    "guestPhone": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "confirmedAt": "2019-08-24T14:15:22Z",    "seatedAt": "2019-08-24T14:15:22Z",    "completedAt": "2019-08-24T14:15:22Z",    "cancelledAt": "2019-08-24T14:15:22Z",    "tabId": "string",    "defaultTabStrategy": "single",    "resources": [      {        "qrCodeId": "8a619d64-dbe8-4c9d-9490-babe22a53a28",        "isPrimary": true,        "position": 0      }    ],    "userName": "string",    "userEmail": "string",    "userPhone": "string",    "tableName": "string",    "location": {      "id": 0,      "name": "string",      "city": "string",      "latitude": 0,      "longitude": 0,      "logoImageUrl": "string"    },    "attribution": {      "firstTouch": {        "capturedAt": "2019-08-24T14:15:22Z",        "utmSource": "string",        "utmMedium": "string",        "utmCampaign": "string",        "utmContent": "string",        "utmTerm": "string",        "referrer": "string",        "landingPage": "string"      },      "bookingTouch": {        "capturedAt": "2019-08-24T14:15:22Z",        "utmSource": "string",        "utmMedium": "string",        "utmCampaign": "string",        "utmContent": "string",        "utmTerm": "string",        "referrer": "string",        "landingPage": "string"      },      "reportedSource": "string",      "recordedAt": "2019-08-24T14:15:22Z"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Check in booking

POST
/api/v1/bookings/{id}/check-in

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Booking ID

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/bookings/497f6eca-6276-4993-bfeb-53cbbbba6f08/check-in"
{  "status": "success",  "data": {    "customFields": [      {        "fieldId": "string",        "key": "string",        "label": "string",        "group": "string",        "type": "string",        "displayValue": "string",        "value": null,        "version": 0,        "status": "string"      }    ],    "metadata": {      "customFields": {}    },    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "locationId": 0,    "tableId": "073fbfcb-cd05-4203-be18-a1ce6f8e4d2d",    "bookingDate": "2019-08-24",    "startTime": "string",    "endTime": "string",    "timezone": "string",    "primaryUserId": null,    "guestCount": 0,    "occasion": "none",    "specialRequests": "string",    "internalNotes": "string",    "notes": [      {        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",        "note": "string",        "sortOrder": 0,        "createdByRetailerUserId": 0,        "updatedByRetailerUserId": 0,        "createdAt": "2019-08-24T14:15:22Z",        "updatedAt": "2019-08-24T14:15:22Z"      }    ],    "status": "pending",    "paymentType": "none",    "depositAmountCents": 0,    "purchaseId": 0,    "confirmationCode": "string",    "bookingSource": "direct",    "estimatedRevenueCents": 0,    "guestName": "string",    "guestEmail": "string",    "guestPhone": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "confirmedAt": "2019-08-24T14:15:22Z",    "seatedAt": "2019-08-24T14:15:22Z",    "completedAt": "2019-08-24T14:15:22Z",    "cancelledAt": "2019-08-24T14:15:22Z",    "tabId": "string",    "defaultTabStrategy": "single",    "resources": [      {        "qrCodeId": "8a619d64-dbe8-4c9d-9490-babe22a53a28",        "isPrimary": true,        "position": 0      }    ],    "userName": "string",    "userEmail": "string",    "userPhone": "string",    "tableName": "string",    "location": {      "id": 0,      "name": "string",      "city": "string",      "latitude": 0,      "longitude": 0,      "logoImageUrl": "string"    },    "attribution": {      "firstTouch": {        "capturedAt": "2019-08-24T14:15:22Z",        "utmSource": "string",        "utmMedium": "string",        "utmCampaign": "string",        "utmContent": "string",        "utmTerm": "string",        "referrer": "string",        "landingPage": "string"      },      "bookingTouch": {        "capturedAt": "2019-08-24T14:15:22Z",        "utmSource": "string",        "utmMedium": "string",        "utmCampaign": "string",        "utmContent": "string",        "utmTerm": "string",        "referrer": "string",        "landingPage": "string"      },      "reportedSource": "string",      "recordedAt": "2019-08-24T14:15:22Z"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Complete booking

POST
/api/v1/bookings/{id}/complete

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Booking ID

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/bookings/497f6eca-6276-4993-bfeb-53cbbbba6f08/complete"
{  "status": "success",  "data": {    "customFields": [      {        "fieldId": "string",        "key": "string",        "label": "string",        "group": "string",        "type": "string",        "displayValue": "string",        "value": null,        "version": 0,        "status": "string"      }    ],    "metadata": {      "customFields": {}    },    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "locationId": 0,    "tableId": "073fbfcb-cd05-4203-be18-a1ce6f8e4d2d",    "bookingDate": "2019-08-24",    "startTime": "string",    "endTime": "string",    "timezone": "string",    "primaryUserId": null,    "guestCount": 0,    "occasion": "none",    "specialRequests": "string",    "internalNotes": "string",    "notes": [      {        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",        "note": "string",        "sortOrder": 0,        "createdByRetailerUserId": 0,        "updatedByRetailerUserId": 0,        "createdAt": "2019-08-24T14:15:22Z",        "updatedAt": "2019-08-24T14:15:22Z"      }    ],    "status": "pending",    "paymentType": "none",    "depositAmountCents": 0,    "purchaseId": 0,    "confirmationCode": "string",    "bookingSource": "direct",    "estimatedRevenueCents": 0,    "guestName": "string",    "guestEmail": "string",    "guestPhone": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "confirmedAt": "2019-08-24T14:15:22Z",    "seatedAt": "2019-08-24T14:15:22Z",    "completedAt": "2019-08-24T14:15:22Z",    "cancelledAt": "2019-08-24T14:15:22Z",    "tabId": "string",    "defaultTabStrategy": "single",    "resources": [      {        "qrCodeId": "8a619d64-dbe8-4c9d-9490-babe22a53a28",        "isPrimary": true,        "position": 0      }    ],    "userName": "string",    "userEmail": "string",    "userPhone": "string",    "tableName": "string",    "location": {      "id": 0,      "name": "string",      "city": "string",      "latitude": 0,      "longitude": 0,      "logoImageUrl": "string"    },    "attribution": {      "firstTouch": {        "capturedAt": "2019-08-24T14:15:22Z",        "utmSource": "string",        "utmMedium": "string",        "utmCampaign": "string",        "utmContent": "string",        "utmTerm": "string",        "referrer": "string",        "landingPage": "string"      },      "bookingTouch": {        "capturedAt": "2019-08-24T14:15:22Z",        "utmSource": "string",        "utmMedium": "string",        "utmCampaign": "string",        "utmContent": "string",        "utmTerm": "string",        "referrer": "string",        "landingPage": "string"      },      "reportedSource": "string",      "recordedAt": "2019-08-24T14:15:22Z"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Confirm booking

POST
/api/v1/bookings/{id}/confirm

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Booking ID

Formatuuid

Query Parameters

sendNotification?boolean

Whether to send the guest a confirmation by email and SMS. Defaults to true. This does not suppress booking webhooks or internal events.

Defaulttrue

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/bookings/497f6eca-6276-4993-bfeb-53cbbbba6f08/confirm"
{  "status": "success",  "data": {    "customFields": [      {        "fieldId": "string",        "key": "string",        "label": "string",        "group": "string",        "type": "string",        "displayValue": "string",        "value": null,        "version": 0,        "status": "string"      }    ],    "metadata": {      "customFields": {}    },    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "locationId": 0,    "tableId": "073fbfcb-cd05-4203-be18-a1ce6f8e4d2d",    "bookingDate": "2019-08-24",    "startTime": "string",    "endTime": "string",    "timezone": "string",    "primaryUserId": null,    "guestCount": 0,    "occasion": "none",    "specialRequests": "string",    "internalNotes": "string",    "notes": [      {        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",        "note": "string",        "sortOrder": 0,        "createdByRetailerUserId": 0,        "updatedByRetailerUserId": 0,        "createdAt": "2019-08-24T14:15:22Z",        "updatedAt": "2019-08-24T14:15:22Z"      }    ],    "status": "pending",    "paymentType": "none",    "depositAmountCents": 0,    "purchaseId": 0,    "confirmationCode": "string",    "bookingSource": "direct",    "estimatedRevenueCents": 0,    "guestName": "string",    "guestEmail": "string",    "guestPhone": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "confirmedAt": "2019-08-24T14:15:22Z",    "seatedAt": "2019-08-24T14:15:22Z",    "completedAt": "2019-08-24T14:15:22Z",    "cancelledAt": "2019-08-24T14:15:22Z",    "tabId": "string",    "defaultTabStrategy": "single",    "resources": [      {        "qrCodeId": "8a619d64-dbe8-4c9d-9490-babe22a53a28",        "isPrimary": true,        "position": 0      }    ],    "userName": "string",    "userEmail": "string",    "userPhone": "string",    "tableName": "string",    "location": {      "id": 0,      "name": "string",      "city": "string",      "latitude": 0,      "longitude": 0,      "logoImageUrl": "string"    },    "attribution": {      "firstTouch": {        "capturedAt": "2019-08-24T14:15:22Z",        "utmSource": "string",        "utmMedium": "string",        "utmCampaign": "string",        "utmContent": "string",        "utmTerm": "string",        "referrer": "string",        "landingPage": "string"      },      "bookingTouch": {        "capturedAt": "2019-08-24T14:15:22Z",        "utmSource": "string",        "utmMedium": "string",        "utmCampaign": "string",        "utmContent": "string",        "utmTerm": "string",        "referrer": "string",        "landingPage": "string"      },      "reportedSource": "string",      "recordedAt": "2019-08-24T14:15:22Z"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Get booking history

GET
/api/v1/bookings/{id}/history

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Booking ID

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/bookings/497f6eca-6276-4993-bfeb-53cbbbba6f08/history"
{  "status": "success",  "data": [    {      "id": 0,      "bookingId": "9a471128-954e-4e64-bde9-e8147015df89",      "eventType": "string",      "eventData": {},      "userId": 0,      "retailerUserId": 0,      "createdAt": "2019-08-24T14:15:22Z"    }  ],  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

List booking members

GET
/api/v1/bookings/{id}/members

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Booking ID

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/bookings/497f6eca-6276-4993-bfeb-53cbbbba6f08/members"
{  "status": "success",  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "bookingId": "9a471128-954e-4e64-bde9-e8147015df89",      "userId": null,      "isPrimary": true,      "guestName": "string",      "guestEmail": "string",      "rsvpStatus": "pending",      "createdAt": "2019-08-24T14:15:22Z"    }  ],  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Add booking member

POST
/api/v1/bookings/{id}/members

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Booking ID

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

userId?number
guestName?string
guestEmail?string
rsvpStatus?string

Value in

  • "pending"
  • "accepted"
  • "declined"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/bookings/497f6eca-6276-4993-bfeb-53cbbbba6f08/members" \  -H "Content-Type: application/json" \  -d '{}'
{  "status": "success",  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "bookingId": "9a471128-954e-4e64-bde9-e8147015df89",    "userId": null,    "isPrimary": true,    "guestName": "string",    "guestEmail": "string",    "rsvpStatus": "pending",    "createdAt": "2019-08-24T14:15:22Z"  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Update booking member

PATCH
/api/v1/bookings/{id}/members/{memberId}

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Booking ID

Formatuuid
memberId*string

Member ID

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

rsvpStatus*string

Value in

  • "pending"
  • "accepted"
  • "declined"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/api/v1/bookings/497f6eca-6276-4993-bfeb-53cbbbba6f08/members/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "rsvpStatus": "pending"  }'
{  "status": "success",  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "bookingId": "9a471128-954e-4e64-bde9-e8147015df89",    "userId": null,    "isPrimary": true,    "guestName": "string",    "guestEmail": "string",    "rsvpStatus": "pending",    "createdAt": "2019-08-24T14:15:22Z"  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Remove booking member

DELETE
/api/v1/bookings/{id}/members/{memberId}

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Booking ID

Formatuuid
memberId*string

Member ID

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/api/v1/bookings/497f6eca-6276-4993-bfeb-53cbbbba6f08/members/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{}

Mark no-show

POST
/api/v1/bookings/{id}/no-show

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Booking ID

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/bookings/497f6eca-6276-4993-bfeb-53cbbbba6f08/no-show"
{  "status": "success",  "data": {    "customFields": [      {        "fieldId": "string",        "key": "string",        "label": "string",        "group": "string",        "type": "string",        "displayValue": "string",        "value": null,        "version": 0,        "status": "string"      }    ],    "metadata": {      "customFields": {}    },    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "locationId": 0,    "tableId": "073fbfcb-cd05-4203-be18-a1ce6f8e4d2d",    "bookingDate": "2019-08-24",    "startTime": "string",    "endTime": "string",    "timezone": "string",    "primaryUserId": null,    "guestCount": 0,    "occasion": "none",    "specialRequests": "string",    "internalNotes": "string",    "notes": [      {        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",        "note": "string",        "sortOrder": 0,        "createdByRetailerUserId": 0,        "updatedByRetailerUserId": 0,        "createdAt": "2019-08-24T14:15:22Z",        "updatedAt": "2019-08-24T14:15:22Z"      }    ],    "status": "pending",    "paymentType": "none",    "depositAmountCents": 0,    "purchaseId": 0,    "confirmationCode": "string",    "bookingSource": "direct",    "estimatedRevenueCents": 0,    "guestName": "string",    "guestEmail": "string",    "guestPhone": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "confirmedAt": "2019-08-24T14:15:22Z",    "seatedAt": "2019-08-24T14:15:22Z",    "completedAt": "2019-08-24T14:15:22Z",    "cancelledAt": "2019-08-24T14:15:22Z",    "tabId": "string",    "defaultTabStrategy": "single",    "resources": [      {        "qrCodeId": "8a619d64-dbe8-4c9d-9490-babe22a53a28",        "isPrimary": true,        "position": 0      }    ],    "userName": "string",    "userEmail": "string",    "userPhone": "string",    "tableName": "string",    "location": {      "id": 0,      "name": "string",      "city": "string",      "latitude": 0,      "longitude": 0,      "logoImageUrl": "string"    },    "attribution": {      "firstTouch": {        "capturedAt": "2019-08-24T14:15:22Z",        "utmSource": "string",        "utmMedium": "string",        "utmCampaign": "string",        "utmContent": "string",        "utmTerm": "string",        "referrer": "string",        "landingPage": "string"      },      "bookingTouch": {        "capturedAt": "2019-08-24T14:15:22Z",        "utmSource": "string",        "utmMedium": "string",        "utmCampaign": "string",        "utmContent": "string",        "utmTerm": "string",        "referrer": "string",        "landingPage": "string"      },      "reportedSource": "string",      "recordedAt": "2019-08-24T14:15:22Z"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Seat booking

POST
/api/v1/bookings/{id}/seat

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Booking ID

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

tabId?string

Optional existing tab ID to link

Formatuuid
createTab?boolean

If true, creates a new tab linked to this booking. The tab will be associated with the booking's primary user and table.

Defaultfalse

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/bookings/497f6eca-6276-4993-bfeb-53cbbbba6f08/seat" \  -H "Content-Type: application/json" \  -d '{}'
{  "status": "success",  "data": {    "customFields": [      {        "fieldId": "string",        "key": "string",        "label": "string",        "group": "string",        "type": "string",        "displayValue": "string",        "value": null,        "version": 0,        "status": "string"      }    ],    "metadata": {      "customFields": {}    },    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "locationId": 0,    "tableId": "073fbfcb-cd05-4203-be18-a1ce6f8e4d2d",    "bookingDate": "2019-08-24",    "startTime": "string",    "endTime": "string",    "timezone": "string",    "primaryUserId": null,    "guestCount": 0,    "occasion": "none",    "specialRequests": "string",    "internalNotes": "string",    "notes": [      {        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",        "note": "string",        "sortOrder": 0,        "createdByRetailerUserId": 0,        "updatedByRetailerUserId": 0,        "createdAt": "2019-08-24T14:15:22Z",        "updatedAt": "2019-08-24T14:15:22Z"      }    ],    "status": "pending",    "paymentType": "none",    "depositAmountCents": 0,    "purchaseId": 0,    "confirmationCode": "string",    "bookingSource": "direct",    "estimatedRevenueCents": 0,    "guestName": "string",    "guestEmail": "string",    "guestPhone": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "confirmedAt": "2019-08-24T14:15:22Z",    "seatedAt": "2019-08-24T14:15:22Z",    "completedAt": "2019-08-24T14:15:22Z",    "cancelledAt": "2019-08-24T14:15:22Z",    "tabId": "string",    "defaultTabStrategy": "single",    "resources": [      {        "qrCodeId": "8a619d64-dbe8-4c9d-9490-babe22a53a28",        "isPrimary": true,        "position": 0      }    ],    "userName": "string",    "userEmail": "string",    "userPhone": "string",    "tableName": "string",    "location": {      "id": 0,      "name": "string",      "city": "string",      "latitude": 0,      "longitude": 0,      "logoImageUrl": "string"    },    "tab": {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "tabMemberId": "eacdba71-5d30-4031-bb4d-d05e652a7917"    },    "attribution": {      "firstTouch": {        "capturedAt": "2019-08-24T14:15:22Z",        "utmSource": "string",        "utmMedium": "string",        "utmCampaign": "string",        "utmContent": "string",        "utmTerm": "string",        "referrer": "string",        "landingPage": "string"      },      "bookingTouch": {        "capturedAt": "2019-08-24T14:15:22Z",        "utmSource": "string",        "utmMedium": "string",        "utmCampaign": "string",        "utmContent": "string",        "utmTerm": "string",        "referrer": "string",        "landingPage": "string"      },      "reportedSource": "string",      "recordedAt": "2019-08-24T14:15:22Z"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Split booking into per-resource tabs

POST
/api/v1/bookings/{id}/split

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Booking ID

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/bookings/497f6eca-6276-4993-bfeb-53cbbbba6f08/split"
{  "status": "success",  "data": {    "tabs": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "qrCodeId": "8a619d64-dbe8-4c9d-9490-babe22a53a28",        "isPrimary": true,        "created": true      }    ],    "createdCount": 0  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Unseat booking

POST
/api/v1/bookings/{id}/unseat

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

id*string

Booking ID

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

reason?string

Why the booking is being unseated (shown on the kitchen correction ticket).

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/bookings/497f6eca-6276-4993-bfeb-53cbbbba6f08/unseat" \  -H "Content-Type: application/json" \  -d '{}'
{  "status": "success",  "data": {    "customFields": [      {        "fieldId": "string",        "key": "string",        "label": "string",        "group": "string",        "type": "string",        "displayValue": "string",        "value": null,        "version": 0,        "status": "string"      }    ],    "metadata": {      "customFields": {}    },    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "locationId": 0,    "tableId": "073fbfcb-cd05-4203-be18-a1ce6f8e4d2d",    "bookingDate": "2019-08-24",    "startTime": "string",    "endTime": "string",    "timezone": "string",    "primaryUserId": null,    "guestCount": 0,    "occasion": "none",    "specialRequests": "string",    "internalNotes": "string",    "notes": [      {        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",        "note": "string",        "sortOrder": 0,        "createdByRetailerUserId": 0,        "updatedByRetailerUserId": 0,        "createdAt": "2019-08-24T14:15:22Z",        "updatedAt": "2019-08-24T14:15:22Z"      }    ],    "status": "pending",    "paymentType": "none",    "depositAmountCents": 0,    "purchaseId": 0,    "confirmationCode": "string",    "bookingSource": "direct",    "estimatedRevenueCents": 0,    "guestName": "string",    "guestEmail": "string",    "guestPhone": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "confirmedAt": "2019-08-24T14:15:22Z",    "seatedAt": "2019-08-24T14:15:22Z",    "completedAt": "2019-08-24T14:15:22Z",    "cancelledAt": "2019-08-24T14:15:22Z",    "tabId": "string",    "defaultTabStrategy": "single",    "resources": [      {        "qrCodeId": "8a619d64-dbe8-4c9d-9490-babe22a53a28",        "isPrimary": true,        "position": 0      }    ],    "userName": "string",    "userEmail": "string",    "userPhone": "string",    "tableName": "string",    "location": {      "id": 0,      "name": "string",      "city": "string",      "latitude": 0,      "longitude": 0,      "logoImageUrl": "string"    },    "attribution": {      "firstTouch": {        "capturedAt": "2019-08-24T14:15:22Z",        "utmSource": "string",        "utmMedium": "string",        "utmCampaign": "string",        "utmContent": "string",        "utmTerm": "string",        "referrer": "string",        "landingPage": "string"      },      "bookingTouch": {        "capturedAt": "2019-08-24T14:15:22Z",        "utmSource": "string",        "utmMedium": "string",        "utmCampaign": "string",        "utmContent": "string",        "utmTerm": "string",        "referrer": "string",        "landingPage": "string"      },      "reportedSource": "string",      "recordedAt": "2019-08-24T14:15:22Z"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Cancel booking by confirmation code

POST
/api/v1/bookings/by-code/{code}/cancel

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

code*string

Booking confirmation code

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

reason?string

Cancellation reason

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/bookings/by-code/string/cancel" \  -H "Content-Type: application/json" \  -d '{}'
{  "status": "success",  "data": {    "customFields": [      {        "fieldId": "string",        "key": "string",        "label": "string",        "group": "string",        "type": "string",        "displayValue": "string",        "value": null,        "version": 0,        "status": "string"      }    ],    "metadata": {      "customFields": {}    },    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "locationId": 0,    "tableId": "073fbfcb-cd05-4203-be18-a1ce6f8e4d2d",    "bookingDate": "2019-08-24",    "startTime": "string",    "endTime": "string",    "timezone": "string",    "primaryUserId": null,    "guestCount": 0,    "occasion": "none",    "specialRequests": "string",    "internalNotes": "string",    "notes": [      {        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",        "note": "string",        "sortOrder": 0,        "createdByRetailerUserId": 0,        "updatedByRetailerUserId": 0,        "createdAt": "2019-08-24T14:15:22Z",        "updatedAt": "2019-08-24T14:15:22Z"      }    ],    "status": "pending",    "paymentType": "none",    "depositAmountCents": 0,    "purchaseId": 0,    "confirmationCode": "string",    "bookingSource": "direct",    "estimatedRevenueCents": 0,    "guestName": "string",    "guestEmail": "string",    "guestPhone": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "confirmedAt": "2019-08-24T14:15:22Z",    "seatedAt": "2019-08-24T14:15:22Z",    "completedAt": "2019-08-24T14:15:22Z",    "cancelledAt": "2019-08-24T14:15:22Z",    "tabId": "string",    "defaultTabStrategy": "single",    "resources": [      {        "qrCodeId": "8a619d64-dbe8-4c9d-9490-babe22a53a28",        "isPrimary": true,        "position": 0      }    ],    "userName": "string",    "userEmail": "string",    "userPhone": "string",    "tableName": "string",    "location": {      "id": 0,      "name": "string",      "city": "string",      "latitude": 0,      "longitude": 0,      "logoImageUrl": "string"    }  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

RSVP to booking

POST
/api/v1/bookings/rsvp

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

confirmationCode*string
guestName*string
guestEmail?string
rsvpStatus*string

Value in

  • "pending"
  • "accepted"
  • "declined"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/bookings/rsvp" \  -H "Content-Type: application/json" \  -d '{    "confirmationCode": "string",    "guestName": "string",    "rsvpStatus": "pending"  }'
{  "status": "success",  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "bookingId": "9a471128-954e-4e64-bde9-e8147015df89",    "userId": null,    "isPrimary": true,    "guestName": "string",    "guestEmail": "string",    "rsvpStatus": "pending",    "createdAt": "2019-08-24T14:15:22Z"  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Get availability

GET
/api/v1/locations/{locationId}/booking-availability

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

locationId*number

Location ID

Query Parameters

date*string

Date to check availability

Formatdate
partySize*number

Number of guests

Range1 <= value
bookingGroupId?string

Optional booking group ID to filter availability by group schedule, table pool, and settings

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/locations/0/booking-availability?date=2019-08-24&partySize=1"
{  "status": "success",  "data": {    "date": "2019-08-24",    "partySize": 0,    "slots": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "tableId": "073fbfcb-cd05-4203-be18-a1ce6f8e4d2d",        "locationId": 0,        "slotDate": "2019-08-24",        "startTime": "string",        "endTime": "string",        "durationMinutes": 0,        "maxCapacity": 0,        "currentBookings": 0,        "status": "available",        "predictedDemandScore": 0,        "optimalPartySizeMin": 0,        "optimalPartySizeMax": 0,        "scheduleId": "b7b4f318-018f-4d71-ac1a-f61e4bfaefbe",        "createdAt": "2019-08-24T14:15:22Z"      }    ],    "tables": [      {        "id": "string",        "name": "string",        "minCapacity": 0,        "maxCapacity": 0,        "availableSlots": [          {            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",            "tableId": "073fbfcb-cd05-4203-be18-a1ce6f8e4d2d",            "locationId": 0,            "slotDate": "2019-08-24",            "startTime": "string",            "endTime": "string",            "durationMinutes": 0,            "maxCapacity": 0,            "currentBookings": 0,            "status": "available",            "predictedDemandScore": 0,            "optimalPartySizeMin": 0,            "optimalPartySizeMax": 0,            "scheduleId": "b7b4f318-018f-4d71-ac1a-f61e4bfaefbe",            "createdAt": "2019-08-24T14:15:22Z"          }        ]      }    ]  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Get availability across a date range

GET
/api/v1/locations/{locationId}/booking-availability-range

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

locationId*number

Location ID

Query Parameters

startDate*string

First date of the range (inclusive)

Formatdate
endDate*string

Last date of the range (inclusive). Must not be more than 62 days after startDate.

Formatdate
partySize*number

Number of guests

Range1 <= value

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/locations/0/booking-availability-range?startDate=2019-08-24&endDate=2019-08-24&partySize=1"
{  "status": "success",  "data": {    "locationId": 0,    "partySize": 0,    "startDate": "2019-08-24",    "endDate": "2019-08-24",    "days": [      {        "date": "2019-08-24",        "status": "available",        "availableSlotCount": 0,        "totalSlotCount": 0,        "firstAvailableTime": null      }    ]  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Get bookings by table

GET
/api/v1/locations/{locationId}/bookings/by-table

Authorization

ApiKeyAuth
X-API-Key<token>

API key authentication. Format: karma_live_* or karma_dev_*

In: header

Path Parameters

locationId*number

Location ID

Query Parameters

date*string

Date to fetch bookings for (YYYY-MM-DD)

Formatdate

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/locations/0/bookings/by-table?date=2019-08-24"
{  "status": "success",  "data": {    "tables": [      {        "tableId": "073fbfcb-cd05-4203-be18-a1ce6f8e4d2d",        "tableName": "string",        "bookings": [          {            "customFields": [              {                "fieldId": "string",                "key": "string",                "label": "string",                "group": "string",                "type": "string",                "displayValue": "string",                "value": null,                "version": 0,                "status": "string"              }            ],            "metadata": {              "customFields": {}            },            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",            "locationId": 0,            "tableId": "073fbfcb-cd05-4203-be18-a1ce6f8e4d2d",            "bookingDate": "2019-08-24",            "startTime": "string",            "endTime": "string",            "timezone": "string",            "primaryUserId": null,            "guestCount": 0,            "occasion": "none",            "specialRequests": "string",            "internalNotes": "string",            "notes": [              {                "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",                "note": "string",                "sortOrder": 0,                "createdByRetailerUserId": 0,                "updatedByRetailerUserId": 0,                "createdAt": "2019-08-24T14:15:22Z",                "updatedAt": "2019-08-24T14:15:22Z"              }            ],            "status": "pending",            "paymentType": "none",            "depositAmountCents": 0,            "purchaseId": 0,            "confirmationCode": "string",            "bookingSource": "direct",            "estimatedRevenueCents": 0,            "guestName": "string",            "guestEmail": "string",            "guestPhone": "string",            "createdAt": "2019-08-24T14:15:22Z",            "updatedAt": "2019-08-24T14:15:22Z",            "confirmedAt": "2019-08-24T14:15:22Z",            "seatedAt": "2019-08-24T14:15:22Z",            "completedAt": "2019-08-24T14:15:22Z",            "cancelledAt": "2019-08-24T14:15:22Z",            "tabId": "string",            "defaultTabStrategy": "single",            "resources": [              {                "qrCodeId": "8a619d64-dbe8-4c9d-9490-babe22a53a28",                "isPrimary": true,                "position": 0              }            ],            "userName": "string",            "userEmail": "string",            "userPhone": "string",            "tableName": "string",            "location": {              "id": 0,              "name": "string",              "city": "string",              "latitude": 0,              "longitude": 0,              "logoImageUrl": "string"            },            "attribution": {              "firstTouch": {                "capturedAt": "2019-08-24T14:15:22Z",                "utmSource": "string",                "utmMedium": "string",                "utmCampaign": "string",                "utmContent": "string",                "utmTerm": "string",                "referrer": "string",                "landingPage": "string"              },              "bookingTouch": {                "capturedAt": "2019-08-24T14:15:22Z",                "utmSource": "string",                "utmMedium": "string",                "utmCampaign": "string",                "utmContent": "string",                "utmTerm": "string",                "referrer": "string",                "landingPage": "string"              },              "reportedSource": "string",              "recordedAt": "2019-08-24T14:15:22Z"            }          }        ]      }    ]  },  "meta": {    "requestId": "string",    "timestamp": "2019-08-24T14:15:22Z",    "executionTimeMs": 0  }}

Tab updated Webhook

Fired on any tab modification: items added, payments received, balance updated, etc. `changes` describes what shifted.

Bookings Optimization

AI-powered booking table optimization