# Changelog (/docs/changelog) Changes that affect you as an integrator — new endpoints and events, changed payloads, deprecations, and notable documentation updates. Newest first. Additive changes (new endpoints, new optional fields, new event types) ship continuously and are listed here. Anything breaking is announced ahead of time and carries a new API version — your existing integration keeps working. BigQuery customer-view changes have a [separate changelog](/docs/bigquery-changelog) and [integration guide](/docs/bigquery). ## 2026-10-20 — Development preview: member identifiers, voucher rules and receipt names [#2026-10-20--development-preview-member-identifiers-voucher-rules-and-receipt-names] Rechecked the development branch through `ab8abdd094`, including 61 non-merge commits after the previous October 19 source audit. These are source-branch changes, not a production deployment announcement. Required migrations, location capabilities and permissions still apply. Earlier generally applicable release coverage remains in place. * **Loyalty identifiers and imports:** programs can configure identifier ordering, scan patterns and searchable/scannable values through `GET`/`PUT`/`POST /api/v1/loyalty/programs/{id}/identifiers` and `PATCH`/`DELETE` on an individual identifier. `POST /api/v1/loyalty/members/resolve` resolves configured codes. Defaults remain Karma card ID, email and phone; a unique guest text field can identify an imported card without email or phone. CSV imports map tiers and unique guest fields, reject identifiers or contacts claimed by different people, and only fill missing contact details on eligible program-owned contactless guests. Hidden programs remain outside guest discovery and self-enrolment; existing membership and staff/integration management are distinct access paths. * **Per-line voucher rates and venue eligibility:** `rule_lines` defines ordered percentage rules with `amountInBasisPoints`, optional included/excluded tags, inclusive charged-unit-price bounds, alcohol conditions and `locationIds`. The first matching rule wins; unmatched lines use the default rate. Venue conditions match the selected location and descendants. Separate `INCLUDE_LOCATION`/`EXCLUDE_LOCATION` restrictions decide whether the voucher is valid at all. Existing item restrictions and maximum discount still apply. Validation carries each line's rate through reservations, purchase confirmation and partial-payment allocation; do not flatten a mixed-rate discount into one percentage. * **Receipt-specific names:** item writes and bulk upserts accept optional `receiptTitle`; variants accept it through variant-group writes. Completed purchase lines retain their receipt text, while internal titles remain available for reports and invoices. Guest, terminal, printed and refund receipts use the receipt name where present. Blank values fall back to the normal name; omitting a variant's field preserves its existing value. This requires the source receipt-title migration and does not establish a new BigQuery customer-view field. * **Custom fields and inventory:** variant groups support custom fields in their contracts and management UI. The existing item editor adds clearer media controls and a menu/template-usage view. Individual and shared prices are distinguished, with an explicit first-shared-price creation path. * **POS and kitchen follow-ups:** product tiles can preset Ambulance or Supplement; unsent remakes begin in the immediate course. Ambulance badges/cards are pink and supplements violet. Remakes stay separate from ordinary history lines and guest receipts omit supplements. Automatic first-course sending no longer releases later waiting courses; staff get an explicit waiting-course action. Add again repeats one committed item with current menu pricing and preserved options/notes, subject to item and cafe-mode limits. Menu/template selection is searchable; Restart confirms cart/payment risk. The active remake chip uses the matching colour and icon, and the mandatory print-template block is labelled Remake band for both kinds. Printer Flow warns when direct location printing bypasses preparation-group flows. * **Billing and invoice controls:** daily AI request/token/cost views distinguish recorded costs, labelled historical estimates, allowances, prepaid tokens and estimated overage. Effective-date token rates preserve earlier usage prices and leave non-token meters on their existing path. Gross request costs are not invoice totals. Invoice settings group POS sending, delivery schedules, inheritance and sharing; timelines show sent times and new-recipient defaults do not rewrite existing recipients. * **Payment, reporting and settings fixes:** guest checkout pays the full remaining split balance after a split change; stale card refusals after a verified capture are acknowledged consistently. Standalone-tip capture fees are finalised, and payment-provider alerts carry clearer state/recovery diagnostics. Caspeco retains staff attribution for guest payments. Analytics PDFs show configured organisation numbers, and location/settings forms restore saved values and use consistent floating save controls. ## 2026-10-20 — Custom voucher providers withdrawn [#2026-10-20--custom-voucher-providers-withdrawn] * **No custom voucher provider.** A location can no longer forward voucher codes to its own HTTPS endpoints, and the custom voucher provider guide is gone. Vouchers are Karma's own; stored value is a gift card. * **Removed endpoints.** `GET` and `PUT /api/v1/locations/{locationId}/voucher-provider` and `POST /api/v1/locations/{locationId}/voucher-provider/test`. * **Vouchers hold no balance.** Creating or updating a voucher with a balance (`GIFT_CARD` that is not a template, `balanceMode: DECREMENTAL` or a `balance` type) returns 400. Gift card templates are unchanged. Validation and reservation responses no longer include `balanceDeductedCents`. ## 2026-10-19 — Upcoming release: changes on dev [#2026-10-19--upcoming-release-changes-on-dev] The changes below are on `dev` but are not yet included in the production branch, `main`, as checked on October 19. Equivalent cherry-picks already on `main` are excluded from this list. This is a release preview, not a production deployment announcement. Feature flags, permissions and required database migrations still apply. This preview groups the generally applicable changes reviewed on October 19. ### Inventory, ingredients and prices [#inventory-ingredients-and-prices] * **Inventory editor and history** — the new item editor brings Essentials, classification, composition, pricing and previews together, with clearer completeness guidance, reviewed AI enhancements and protection for unsaved drafts. Item configuration history supports listing and reading immutable revisions and restoring an earlier configuration as a new revision: `GET /api/v1/inventory/{id}/versions`, `GET /api/v1/inventory/{id}/versions/{versionId}` and `POST /api/v1/inventory/{id}/versions/{versionId}/restore`. Restore requires `expectedVersionId`; conflicting edits return `409`. History starts with the first captured baseline, excludes stock-only changes, and cannot restore inherited or integration-managed items. * **Optional ingredient management** — a capability-controlled ingredient and preparation library adds recipes, purchase-pack/yield costing, optional nutrition, canonical allergen review, CSV import and affected-dish availability controls. Management routes are under `/api/v1/locations/{locationId}/ingredients`; published allergen information is read through `GET /api/v1/locations/{locationId}/items/{itemId}/food-information`. Publishing requires a saved, reviewed recipe; unpublished information is `null`, and changed dependencies require review. Calculated costs remain incomplete when required inputs are missing. * **Reviewed stocktakes** — the optional new inventory workflow supports item and ingredient counts through `GET`/`POST /api/v1/locations/{locationId}/stocktakes`. Counts are reviewed before confirmation; stale stock or definition tokens reject the write, and retrying the same submission does not apply it twice. Ingredient management and the new inventory workflow are enabled separately. * **Classification and accounts** — category settings, classification presets and explicit item account overrides are available in the editor. Purchase cost can be calculated from the ingredient recipe. Existing item-type strings, legacy tags and the documented stock limits remain distinct contracts; the [inventory guide](/docs/inventory-items) describes the write fields and limits. * **Consistent marketplace pricing** — checkout and Wolt, Foodora and Uber Eats menu publication share the item-pricing implementation, including nearest-location overrides, shared/cluster prices, channel rules and linked-choice prices. Marketplace publication treats scheduled rules as inactive and skips items without a resolvable channel price. Explicit zero-priced choices remain free; negative choices deduct their amount. This change introduces no public price-resolution endpoint. * **Marketplace menu coverage** — Foodora and Uber Eats accept inherited menus and roots typed `menu`; Wolt no longer publishes a sibling store's channel assignment. Publication excludes inactive options while retaining required option groups hidden from normal menu navigation. API-synchronized menus can be reordered in the backoffice QR view. ### Ordering, payments and exports [#ordering-payments-and-exports] * **Pickup availability** — available times follow the actual dishes in the cart, including inherited menu placements and breaks within a pickup slot. Order creation applies the same check. Checkout recovers when a slot becomes unavailable, moves past days with no remaining valid times, and excludes digital or shipped items from pickup constraints. A failed schedule lookup returns an error rather than offering unchecked times. * **Payment recovery** — late authorizations and provider failures are reconciled against verified provider state, checkout cancellation checks are scoped to the payment, and transient Swish initiation is retried only after absence of an existing payment has been verified. Storefront wallet checkout can recover on resume. Saved-card checkout uses the merchant account's CVC capability instead of always requiring CVC. * **Historical refunds and Save fees** — eligible historical purchases can use the refund flow, and Save refunds include the refundable service-fee portion. Purchase responses retain `appliedFees` and `refunds`, including `feeType` and `serviceFeeRefundAmountCents` where applicable. These response fields do not establish new BigQuery customer-view columns. * **Caspeco refund corrections** — confirmed refunds whose original sales have been exported are sent as correction tickets dated on the refund's day, with the original receipt reference. Corrections are enabled by default; `refundCorrectionsFrom` can restrict the refund-date range or be set to `off`. Accepted exports are deduplicated, failed ones can retry, concurrent deliveries are guarded, and tip-only corrections report zero guests. Existing sales days are not overwritten. * **Invoice corrections** — corrected invoices are fully credited and replaced. Billing supports token allowances, applies metered units to usage estimates, and reconciles card-paid invoices with Fortnox. Locations can hide or temporarily mute the late-payment banner. * **Storefront ratings and confirmation content** — locations can turn off Karma post-order ratings through `storefrontRatingsEnabled`; ratings stay enabled unless explicitly disabled. The confirmation editor adds headings, bold text, lists, images and feedback links, with previews of storefront buttons and kiosk QR codes. Existing Markdown remains editable. * **Receipt voucher privacy** — printed and emailed receipts use configured public discount names or a generic discount label rather than exposing redemption codes in line labels. Voucher codes shown in receipt payment summaries are masked; this changes receipt presentation, not stored sales amounts. * **BigQuery price-cluster views** — the October 19 development/staging sync is recorded separately in the [BigQuery changelog](/docs/bigquery-changelog): the checked customer datasets expose four additional views, bringing their inventories to 449 columns across 30 views. This does not establish production customer-view availability. * **Table-group reporting** — the breakdown distinguishes tables without a group from over-the-counter sales without a table; the reporting response includes `hasTable`. ### POS, kitchen and backoffice [#pos-kitchen-and-backoffice] * **Ambulance tickets and house-paid supplements (supplemang)** — staff can mark a line as a charged remake or a house-paid supplement. The server forces supplements and their children to zero price; they stay visible to staff and are omitted from guest tabs and receipts. Remakes receive separate kitchen tickets and KDS cards. Order input uses `ambulance_kind` (`charged` or `supplement`); returned line data exposes `ambulanceKind`. A remake cannot also be a zero ticket. Printing provides separate `ambulance_ticket` and `supplement_ticket` templates with the `ambulance_banner` block. The follow-up fixes duplicate slips caused by printer-less preparation groups and removes redundant per-line banners on an already framed remake ticket. Both KDS boards highlight remakes; order history and purchase details badge them, and purchase lines expose nullable `ambulanceKind`. Both remake templates support buzzers, and printer flows can route ordinary, ambulance and supplement tickets separately through `ticket_type_filter`. This feature and the seeded buzzer-template update require their central database migrations. * **Coursing and tab lines** — reset coursing from the course picker or a menu action to hold a late guest's course. Devices can hide the next-course button on wide screens and choose tab-line ordering, with kitchen-ticket order as the default. Lines without a kitchen sort order have a configurable order. Quantity-based line splitting supports as many parts as there are units. * **Course counts and menu colors** — each unsent course header shows the summed portion quantity still to send. Menu builders can select multiple grid tiles or action-bar items and apply a level color, custom color or reset to the product color in one update/autosave. The Change color control sits in the builder palette; detached layout references are recolored on the layout itself. * **Finding tabs and navigating menus** — filter tables to those with open tabs and counter tabs by takeaway, retain counter-tab filters and My sales across reloads, and show clearer empty states and guest counts. The quick menu becomes a touch-sized dialog with clearer tiles and a restart action. Reusable templates honor return-to-root, action types have descriptions, and product text, quick-pay titles, breadcrumbs and action pickers fit their controls. * **Device settings** — station synchronization covers the POS settings exposed in Devices, including PIN on open, grid text size, counter-tab filters and the tab panel's starting view. Devices can hide prices on product tiles. The send-message dialog supports a configured station list and a searchable multi-select picker; table-map and table-list controls have larger touch targets. * **Kitchen printing** — tickets can sort items by descending quantity, show takeaway alongside table details, and show secondary preparation settings only for kitchen tickets. * **Backoffice polish** — dialog dropdowns scroll and stay interactive above the form; the new-version notification sits at the top center with larger actions and responsive wrapping, and loading uses animated KARMA letters. Surplus timelines use the venue timezone. CRM notes and activities show their full text, and shared-photo caption choices and previews are clearer. * **Staff management permissions** — account-wide edits, PIN changes, deactivation and password resets require authority over all affected locations; removing location access checks that location. Except for self-service and Karma staff rules, callers must hold all the target's permissions plus additional authority. `GET /api/v1/retailer/users/{id}` returns `canManage` so clients can reflect the server decision. * **Maintenance** — the pricing implementation moves into a shared package, deprecated request-ID logging configuration and an obsolete Dependabot schedule are removed, and regression tests cover late terminal authorization cancellation. Formatting and editor refactors are included in the behavior summaries above. ## 2026-10-12–18 — Updates on the production branch [#2026-10-1218--updates-on-the-production-branch] This roundup covers direct commits and cherry-picks recorded on `main` during October 12–18, using Europe/Stockholm dates. It includes production-only fixes that would be missed by a `dev` comparison. Branch inclusion does not by itself verify a running deployment. * **October 17 — POS touch quantities:** a touch or pen tap opening a quantity dialog no longer also presses the keypad beneath the finger. This preserves the product's default portion. The fix was cherry-picked to `main`. * **October 15 — Saved-card capability:** the common API exposes the account-specific CVC capability. The October 12 app fix restored CVC where required by live Adyen; the pending checkout change above consumes the capability to skip it only for enabled accounts. * **October 12–15 — Commercial Team Pulse and progression:** live team slides use authoritative daily data and durable events, include support/onboarding, active venues and per-person activity, and rotate the full leaderboard. Signing and won-back celebrations use verified events and support display-only replay; won-back celebrations name the owner. Revenue charts stop at the current time. Revenue XP includes verified Swish transactions checked against the canonical intent, attributes sole active contributors, deduplicates commitment awards, adjusts original sellers after pricing changes, excludes unanswered calls, and uses a Stockholm daily activity limit. Portfolio cards show transaction XP. * **October 13 — Payments and POS:** verified late-authorization cancellations are reconciled; manually applied vouchers no longer carry into the next order. The printed HOLD banner fills the ticket width. * **October 12 — Combined reporting:** combined SIE/CSV/PDF exports, Fortnox vouchers and purchase summaries use each included location's own calendar/business-day setting. The exporting location follows the caller's setting; children follow their saved setting, defaulting to calendar day. Compare combined totals with the sum of those per-location windows. * **October 12 — Refund labels, inheritance and billing:** refund receipts print translated reason labels, including Swedish “Annat”; inherited course names and nearest-parent prices resolve correctly. Inherited users are excluded from billable seats, and Workspace activation explains prerequisites and missing migrations. * **October 12 — Kaia and scheduled articles:** stock reports respect filters and resolve serving courses; scheduled MCP sessions use the common API signing key. Publishing an article with a future publication date schedules its visibility across article APIs and readers. The scheduling change was cherry-picked to `main`. * **Operational maintenance:** Adyen report-cost processing is batched and bounded, the retired payment service is excluded from production deployment waves, and developer schema tests use the configured Vitest runner. Related test and formatting changes are included without separate feature announcements. ## 2026-10-15 — Inventory write schemas list every property [#2026-10-15--inventory-write-schemas-list-every-property] * **No open-ended request bodies.** The create and update schemas for inventory items now list every property they accept, and the reference no longer shows `[key: string]: any` on them. Keys not in the schema were already ignored and still are; they are now also left out of the reference. `metadata` (your own keys) and `context` stay free-form, and the [inventory guide](/docs/inventory-items) explains both. * **`basePrice` is optional on create.** It never set the price; use `pricings` or `pricingGroupId`. * **Availability.** `isAvailable` and `available` are no longer listed on update: they never had an effect. Use `POST /api/v1/inventory/{itemId}/availability`. * **Every property described.** Pricing rule types and their `metadata`, measurement, custom fields, images and classification now have descriptions. The item response marks properties returned only by the list or the single-item endpoint, and no longer lists `basePrice` or `karmaCutPercentage`, which are never returned. ## 2026-10-13 — Inventory validation and reference [#2026-10-13--inventory-validation-and-reference] * **Stricter inventory write validation.** These requests used to fail with a 500, or in the case of `vatValue` store a VAT rate a hundred times too high. They now return a 400: * `itemType` longer than 50 characters; * a `visibility` value outside `POS`, `KIOSK`, `TAKEAWAY`, `ONLINE` and `GENERAL`, or a repeated value; * `vatValue` above 100. Writes take a percentage (`12`), while reads return basis points (`1200`). * **Inventory reference.** The item response now documents every field the API returns, including `pricings`, `variantGroupIds`, `printerGroupIds`, `accountIds`, stock, kitchen and inheritance fields. The [inventory guide](/docs/inventory-items) is rewritten: * which `itemType` values carry behaviour; * that tags are never created, unknown ones are skipped silently, and `tags` on update replaces the whole set, `CATEGORY_PRIMARY` included; * that `visibility` is stored but has no effect; * the read/write units of `vatValue`. ## 2026-10-12 — Inventory and BigQuery documentation clarification [#2026-10-12--inventory-and-bigquery-documentation-clarification] * **Inventory writes:** the [inventory guide](/docs/inventory-items) distinguishes extensible `itemType` strings from legacy item-type references and sales-line classifications. It documents empty strings, the storage limit, visibility memberships, existing-reference relationships, tag replacement and VAT precedence. The write reference now describes fields already forwarded by the handlers; no new inventory feature is announced. The current create handler's `basePrice` compatibility limitation is explicit: use `pricings` or a shared-price ID and verify the resulting price. * **BigQuery reporting:** the [guide](/docs/bigquery) now includes verified split-payment examples, modifier/article lookup fallbacks, historical discounted VAT, prepaid-code scope, EH member lookup and refund-contract limitations. See the separate [BigQuery changelog](/docs/bigquery-changelog) for the dated dev/test schema observations. ## 2026-10-07 — Production payment and receipt fixes [#2026-10-07--production-payment-and-receipt-fixes] * **Swish refunds** — corrected refund handling for Swish payments processed through Adyen, including refunds requested while capture is still pending. * **Terminal modifications** — cancellation and refund requests now use the POS credentials bound to the original terminal payment. * **Digital receipts** — restored the digital-receipt QR code on terminal receipts. ## 2026-10-06 — Production release [#2026-10-06--production-release] The latest production release brings the following integration changes to the main API. * **Shared prices and price clusters** — `GET`/`POST /api/v1/prices` and `PUT /api/v1/prices/{id}` manage reusable price definitions. Link inventory items with `pricingGroupId`; updates require the latest `version`. The `/api/v1/price-clusters` endpoints manage grouped item prices and assignments to descendant locations, including linked shared prices and location overrides. * **Inventory discovery** — inventory listing supports pricing-aware filters and sorting. Catalogue changes now reach inheriting locations through realtime updates, and catalogue version tags remain distinct after a lost version counter. * **Refund controls and quantities** — `/api/v1/refunds/settings` exposes location controls for amount, product and partial refunds, alongside configurable reasons. Product refund lines accept `quantityCents` in hundredths of a unit: `100` means one unit. An amount-only refund does not record a returned quantity; do not infer units from the refund amount. * **Receipt observability** — receipt-decision and receipt-status endpoints explain skipped receipts and expose pending, printed or failed jobs. Use the receipt request's correlation ID to look up its status. * **Reporting** — staff sales reports can attribute sales to the staff member who took payment. A parent location can apply its prepaid-account mapping to descendant locations in combined SIE exports. * **Order-confirmation settings** — `/api/v1/locations/{locationId}/order-confirmation-settings` configures recipient rules by channel and item. Its `/preview` endpoint renders example HTML and plain text without sending email. Newly enabled rules apply to orders first received after enabling. * **BigQuery source changes** — refund quantity, refund controls and price-cluster source migrations were released to production. Source rollout does not establish customer-view availability; see the [BigQuery changelog](/docs/bigquery-changelog) for the environment-specific observations and export implications. ## 2026-09-24 [#2026-09-24] **Objects and fields.** The API reference now includes the Objects & Fields API: typed, versioned custom fields on items, guests, reservations, tables, locations, tabs, orders and purchases, with a [guide](/docs/custom-fields) covering definitions, values, the projection on normal responses and search. * **Guides** — [rate limits](/docs/rate-limits), [placing an order](/docs/place-an-order), [reading sales data](/docs/sales-data), [pushing surplus from a POS](/docs/surplus-from-pos) and the custom voucher provider contract (withdrawn on 2026-10-20). * **Reference refreshed** — 467 operations, adding gift card, invoice, reporting, payout report and print job endpoints alongside the fields API. * **Environments** — the staging API is `common-api.staging.karma.life`. ## 2026-09-23 — Upcoming staging API update [#2026-09-23--upcoming-staging-api-update] These changes subsequently shipped in the [October 6 production release](#2026-10-06--production-release). The text below records the original staging announcement. The changes below are planned for staging. The API reference will show their full schemas when the release is deployed. * **Shared prices:** `GET`/`POST /api/v1/prices` and `PUT /api/v1/prices/{id}` will let you create reusable prices and link inventory items through `pricingGroupId`. Inventory responses will include the selected price and calculated prices by channel. * **Inventory discovery:** `GET /api/v1/inventory` will add filters for title, pricing name, local or inherited source, and effective price, plus pricing-aware sorting. * **Receipt jobs:** New receipt-decision and receipt-status endpoints will expose why a receipt was skipped and whether a requested receipt is still pending, printed, or failed. Terminal receipt requests will return a correlation ID for status lookup. * **Webhooks:** Existing inventory, booking, order, and tab events will be able to include API-readable custom fields in `customFields` and `metadata.customFields`. No new event type is introduced. The planned REST reference removes no existing operation. Price amounts use the location's currency units, and shared-price updates will require the latest version. ## 2026-08-12 [#2026-08-12] **API reference refreshed.** The reference now covers 513 operations, up from 477 — including retailer user management, guest profile and alias endpoints, additional location endpoints, and a new reporting endpoint. * **New sections** — Customers (guest records, profiles and aliases) and retailer user management under Staff & Access. ## 2026-08-02 [#2026-08-02] **New developer site.** This site replaces the previous API documentation. It covers the REST API and webhook events in one place, with a request playground on every endpoint. * **Webhooks reference** — all 31 outbound events now documented with their full payload schema, delivery envelope and routing, rather than a hand-maintained subset. * **Markdown for tools** — every page is also served as plain markdown at the same URL with a `.md` suffix, plus [`llms.txt`](/llms.txt) and [`llms-full.txt`](/llms-full.txt) indexes, so AI assistants and scripts can read the docs directly. * **Environment switcher** — the reference for the development and staging environments is published separately, so you can read the docs that match the environment you are integrating against.