# Docs

- [Introduction](/docs): REST APIs and webhooks for ordering, bookings, menus and payments.
- [Changelog](/docs/changelog): Changes to the Karma API, webhook events and this documentation.

- **Guides**
- [Rate limits](/docs/rate-limits): How many requests an API key may make per hour, and how to read the limit headers.
- [Receiving webhooks](/docs/webhooks): How Karma delivers events to your endpoint — the envelope, signing, retries and ordering.
- [Objects and fields](/docs/custom-fields): Attach typed, versioned fields to items, guests, reservations, tables, locations, tabs, orders and purchases, and read or write them through the API.
- [Variant custom fields](/docs/variant-custom-fields): Read and write group attributes and linked-item fields, and submit customer answers for selected variants.
- [Booking attribution](/docs/booking-attribution): Capture marketing discovery, booking acquisition and guest-reported sources separately from booking and ordering channels.
- [Creating inventory items](/docs/inventory-items): Inventory item types, prices, VAT, tags, visibility and existing-reference relationships.
- [Placing an order](/docs/place-an-order): Create an order at a Karma location from an external system in a single call.
- [Reading sales data](/docs/sales-data): How to interpret purchases and line items the way Karma does, and how to export a day's sales reliably.
- [BigQuery data sharing](/docs/bigquery): Connect to Karma's customer-scoped BigQuery views and build reliable sales, refund, menu, and operational exports.
- [BigQuery field reference](/docs/bigquery-fields): All columns advertised by an example customer dataset, with types, meanings, and documented limitations.
- [BigQuery changelog](/docs/bigquery-changelog): Dated customer-view schema observations, integration changes, and known BigQuery limitations.
- [Pushing surplus from your POS](/docs/surplus-from-pos): Push end-of-day surplus from your own POS or inventory system so it appears in the Karma app at a discount.
- [Shared prices](/docs/shared-prices): Create reusable prices and assign them to local or inherited inventory items.

- **APIs**
- Ordering API
  - [Orders](/docs/ordering/orders): Customer orders and order management
  - [Tabs](/docs/ordering/tabs): Customer tabs and running bills
  - [Coursings](/docs/ordering/coursings): Multi-course meal sequencing
  - [Extended Waiting Time](/docs/ordering/extended-waiting-time): Extended waiting times during busy periods
  - [Notes](/docs/ordering/notes): Notes attached to tabs and orders
  - [Serving Centers](/docs/ordering/serving-centers): Serving centers that prepare and hand out orders
  - [Tabs Auto Close Settings](/docs/ordering/tabs-auto-close-settings): When open tabs close automatically
  - Events
    - [Order cancelled](/docs/ordering/events/order.cancelled): Fired when an order is cancelled. Includes the location, tab, cancelling retailer user and an optional reason.
    - [Order completed](/docs/ordering/events/order.completed): Fired when an order is marked complete in the KDS.
    - [Order (kitchen dispatch) created](/docs/ordering/events/order.created): Fired when items are committed to the kitchen (POST /api/v1/inventory/commit). One event per dispatch.
    - [Items added to an existing order](/docs/ordering/events/order.items_added): Fired when items are added to a kitchen dispatch that already exists.
    - [Order requires payment](/docs/ordering/events/order.payment_required): Fired when an order needs payment (e.g. INSTANT flow, or tab settlement).
    - [Order reversed (void)](/docs/ordering/events/order.reversed): Fired when a kitchen dispatch is reversed — e.g. void requested or booking unseated. Carries full item snapshots so subscribers (printer-service) can produce KORRBONG void tickets.
    - [Order updated](/docs/ordering/events/order.updated): Fired on any KDS state transition or detail change. `changes` describes what shifted.
    - [Tab closed](/docs/ordering/events/tab.closed): Fired when a tab is manually closed or administratively aborted. This is a lifecycle signal, not proof of payment; use tab.payment_completed for payment success.
    - [Tab member added](/docs/ordering/events/tab.member_added): Fired when a guest joins an existing tab (POST /api/v1/tabs/:id/members).
    - [Tab opened](/docs/ordering/events/tab.opened): Fired when a new tab is created (e.g. POST /api/v1/tabs/resolve, or table seating).
    - [Tab payment completed](/docs/ordering/events/tab.payment_completed): Authoritative success signal for one payment, which may cover only part of the tab. It does not mean the tab was manually closed. Use tabSettled (or remainingBalanceCents) to decide whether the tab is fully paid, and use tab.closed only for manual or administrative closure.
    - [Tab payment failed](/docs/ordering/events/tab.payment_failed): Authoritative failure signal for a tab payment. Includes error code and message for debugging.
    - [Tab payment initiated](/docs/ordering/events/tab.payment_initiated): Fired when a payment is initiated (POST /api/v1/tabs/:id/pay). Mode-specific fields (`itemCount`, `itemIds`) are present only for ITEM mode.
    - [Tab updated](/docs/ordering/events/tab.updated): Fired on any tab modification: items added, payments received, balance updated, etc. `changes` describes what shifted.
- Booking API
  - [Bookings](/docs/booking/bookings): Table reservations and booking management
  - [Bookings   Optimization](/docs/booking/bookings-optimization): AI-powered booking table optimization
  - [Bookings   Settings](/docs/booking/bookings-settings): Location booking settings and configuration
  - [Bookings   Users](/docs/booking/bookings-users): Guest user search and creation for bookings
  - [Bookings   Waitlist](/docs/booking/bookings-waitlist): Booking waitlist management
  - [Tables](/docs/booking/tables): Restaurant table management
  - [Table Groups](/docs/booking/table-groups): Table grouping and floor plans
  - [Booking Groups](/docs/booking/booking-groups): Grouping of related bookings
  - [Time Slots](/docs/booking/time-slots): Available time slots for orders and bookings
  - [Time Slots Settings](/docs/booking/time-slots-settings): Location configuration for order time slots
  - [Capacity Settings](/docs/booking/capacity-settings): Time slot capacity configuration and limits
  - [Notes](/docs/booking/notes): Notes attached to tabs and orders
  - Events
    - [Booking cancelled](/docs/booking/events/booking.cancelled): Fired when a booking is cancelled.
    - [Booking completed](/docs/booking/events/booking.completed): Fired when a booking is marked complete. The full booking object is spread into `data`.
    - [Booking confirmed](/docs/booking/events/booking.confirmed): Fired when a booking transitions to confirmed. The full updated booking is spread into `data`.
    - [Booking created](/docs/booking/events/booking.created): Fired when a new booking is created. The full booking object is spread into `data`.
    - [Booking marked no-show](/docs/booking/events/booking.no_show): Fired when a booking is marked as no-show. The full booking is spread into `data`.
    - [Booking seated](/docs/booking/events/booking.seated): Fired when guests are seated. Includes the full booking and an optional `tabId` if seating opened a tab.
    - [Booking unseated](/docs/booking/events/booking.unseated): Fired when seating is undone. Lists all kitchen dispatches that were reversed (each will also fire `order.reversed`).
    - [Booking updated](/docs/booking/events/booking.updated): Only the modified fields appear in `changes`.
    - [Waitlist entry converted to booking](/docs/booking/events/waitlist.converted): Fired when a waitlist entry is converted into a booking. Links the entry to the new booking ID.
    - [Waitlist entry joined](/docs/booking/events/waitlist.joined): Fired when a guest joins the waitlist. The full waitlist entry is spread into `data`.
    - [Waitlist entry notified](/docs/booking/events/waitlist.notified): Fired when a waitlist entry is notified that a table is available.
    - [Waitlist entry removed](/docs/booking/events/waitlist.removed): Fired when a waitlist entry is removed.
- Menu API
  - [Inventory](/docs/menu/inventory): Menu items, products, and modifiers
  - [Menu Layouts](/docs/menu/menu-layouts): Menu structure and organization
  - [Variant Groups](/docs/menu/variant-groups): Product options and modifiers
  - [Custom Tags](/docs/menu/custom-tags): Labels and categorization
  - [Category Tags](/docs/menu/category-tags): Category tag catalog for classifying inventory items
  - [Translations](/docs/menu/translations): Multi-language translations for inventory and menus
  - [V A T Rates](/docs/menu/vat-rates): VAT rates available for a location's country
  - [Item Accounts](/docs/menu/item-accounts): Bookkeeping accounts for sales lines, per item
  - Events
    - [Inventory item created](/docs/menu/events/inventory.created): Fired when a new inventory item is created (POST /api/v1/inventory). The full item object is included in `data` along with `locationId`.
    - [Inventory item soft-deleted](/docs/menu/events/inventory.deleted): Fired when an inventory item is soft-deleted (DELETE /api/v1/inventory/:id). The row remains in the database with `deleted: true`.
    - [Inventory item updated](/docs/menu/events/inventory.updated): Fired when an inventory item changes (PUT /api/v1/inventory/:id), from channel-assignment changes affecting the item (`changes.channels_updated: true`), or on scheduled-pricing transitions (reason-only shape without itemId).
- Payments API
  - [Checkout](/docs/payments/checkout): Cart pricing quotes before payment
  - [Purchase Intents](/docs/payments/purchase-intents): Payment intents for purchases — create, track, and settle a payment
  - [Payment Methods](/docs/payments/payment-methods): User and location payment methods management
  - [Prepaid Types](/docs/payments/prepaid-types): Prepaid payment categories for externally-paid tabs (e.g. third-party channels)
  - [Gift Cards](/docs/payments/gift-cards): Gift card issuance, balance, and redemption
  - [Purchases](/docs/payments/purchases): Purchase history, transaction details, and refunds
  - [Settlements](/docs/payments/settlements): Tab settlements and payment groupings
  - [Invoices](/docs/payments/invoices): Invoice management, recipients, and location settings
  - [Invoice Recipients](/docs/payments/invoice-recipients)
  - [Terminals](/docs/payments/terminals): Payment terminal management
- Loyalty API
  - [Loyalty](/docs/loyalty/loyalty)
  - [Loyalty Programs](/docs/loyalty/loyalty-programs): Customer loyalty programs, points, tiers, and rewards
  - [Loyalty Self Service](/docs/loyalty/loyalty-self-service)
  - [Loyalty Wallet Passes](/docs/loyalty/loyalty-wallet-passes)
  - [Vouchers](/docs/loyalty/vouchers): Discount vouchers and promotions
- Surplus API
  - [Surplus](/docs/surplus/surplus): Surplus inventory — food items pushed to Karma for end-of-day sale at a discount
  - Events
    - [Surplus entry added](/docs/surplus/events/surplus.added): Fired when a venue adds surplus (New Save) inventory. Drives consumer push notifications.
- Locations API
  - [Locations](/docs/locations/locations): Location management and creation
  - [Location Maps](/docs/locations/location-maps): Floor plans and seating layouts
  - [Channels](/docs/locations/channels): Sales channels (dine-in, takeaway, delivery)
  - [Schedules](/docs/locations/schedules): Operating hours and special schedules
  - Events
    - [Location operating hours updated](/docs/locations/events/location.hours.updated): Broadcast when a schedule rule for a location changes — lets storefronts and clients refresh open/closed status.
- Customers API
  - [Customers](/docs/customers/customers): Location-scoped guest user records, overrides, and editing
  - [Users](/docs/customers/users): End user management and lookup
- Staff & Access API
  - [Staff](/docs/staff/staff)
  - [Retailer Users](/docs/staff/retailer-users): Retailer user management and invitations
  - [Roles](/docs/staff/roles): Role management with permission assignment
  - [Permissions](/docs/staff/permissions): Permission registry and management
- Analytics API
  - [Analytics](/docs/analytics/analytics): Enterprise real-time analytics with BigQuery
  - [Reporting](/docs/analytics/reporting): Purchase summary reports and financial reporting
  - [Payout Reports](/docs/analytics/payout-reports): Payout report generation and download
  - [C C R Reports](/docs/analytics/ccr-reports): Cash-register compliance (CCR) report generation
  - [Data Streaming](/docs/analytics/data-streaming): Real-time data streaming and sync
  - [Reviews](/docs/analytics/reviews): Customer reviews and feedback for purchases
  - [Cost Centers](/docs/analytics/cost-centers): Bookkeeping cost centers and the location default
- Hardware API
  - [Printers](/docs/hardware/printers): Receipt and ticket printer management with CloudPRNT URLs
  - [Print Templates](/docs/hardware/print-templates): Print template management for receipts and tickets
  - [Printer Flows](/docs/hardware/printer-flows): Routing of kitchen tickets between printer groups
- Objects & Fields API
  - [Object fields](/docs/fields/object-fields)
- Platform API
  - [A P I Keys](/docs/platform/api-keys): Manage API keys, their permissions, and usage
  - [Webhooks](/docs/platform/webhooks): Webhook subscriptions and event notifications
  - [Alerts](/docs/platform/alerts): System notifications and warnings
  - [Helpers](/docs/platform/helpers): High-level helper endpoints that combine multiple operations into a single call (e.g. find-or-create item and add surplus)
  - [Public](/docs/platform/public): Simplified endpoints for external integrations — place orders without complex setup
  - [Other](/docs/platform/other)
  - [C W I](/docs/platform/cwi): Company-Wide Items (CWI) management via EAN