Guide
Changelog
This changelog lists changes that affect clients using the private APIs.
Use X-API-VERSION to select a supported version. Requests without this header use 29-10-2026, the latest version.
Changes available at all API versions
Fixed surcharges on modifiers
Product groups add an explicit modifiers UUID list. Merchant Console accepts merchant-owned modifier references on product-group creation, editing and bulk editing. Creation defaults to []; omitted single edits retain membership, supplied lists replace it and [] clears it. Bulk editing appends unique memberships; omitted or empty lists retain existing membership. Items and categories never imply modifier membership. Discounts, taxes and percentage surcharges continue using item membership only.
Catalog surcharges add apply_to_free_items, defaulting to false. Create, edit and bulk-edit requests accept the toggle for every calculation type. Omitted edits retain each current value; explicit false disables it. Only fixed surcharges with a product group consume this setting. When false, fully discounted or zero-value bundled lines and zero-priced modifier selections are skipped. When true, those lines and selections remain eligible. Free status uses prices and discounts, excluding surcharges and taxes.
Fixed product-group surcharges independently count matching parent items, direct modifiers and meal modifiers. Each parent match contributes fixed amount × parent quantity; each modifier occurrence contributes fixed amount × modifier quantity × parent quantity. Matches are additive. Contributions remain one existing item-scoped surcharge allocation per source surcharge per parent line, preserving source UUID, name and tax exemption. Percentage, fixed order-scoped and system surcharge calculations are unchanged. No new order surcharge fields or API version are required.
Persisted POS Sales Reports
Merchant Console adds POST /merchants/{uuid}/reports/pos-sales to synchronously generate a PDF for one outlet using outlet, start and end. Requires a YQueue POS merchant, view_pos_sales_report and permitted-outlet access. UTC reporting periods are inclusive and limited to 48 hours. The A4 PDF shares the POS sales-summary presentation, including all cards, descriptions, metrics and breakdowns; POS requests continue to return JSON and create no history.
The new view_pos_sales_report permission is exposed through existing console permission discovery only for YQueue POS merchants. It can be granted to custom staff roles through staff editing; existing daily/hourly sales reports retain view_sales_report.
POST /merchants/{uuid}/reports/search returns page-paginated retained reports with fresh one-hour signed download URLs. Supply filters.types: [pos_sales]; unavailable types return a field validation error with HTTP 400; optional outlet filters are restricted to permitted outlets. Optional date filters select generation timestamps, without the generation interval limit. Defaults are page 1 and 25 results, with at most 25 per page; newest reports appear first. Filenames contain both reporting bounds in the merchant's timezone and a unique report UUID, so repeated generations remain separate.
POS Sales Summary and its merchant-console PDF now display a maximum of 1,000 Underpaid Orders entries. When more exist, the metric description says that only the first 1,000 are shown and recommends a shorter reporting period. This affects only the unpaid exception breakdown; financial totals, overpaid orders and other sections still cover the full period. The response shape is unchanged.
These are additive endpoints available at every supported API version. See Generate POS Sales Report and Search Persisted Merchant Reports.
iglooX stamps, points and POS refunds
Kiosk and Online Ordering payment configurations add stamps and points under igloox; POS customer lookup adds those collections beside stored_value and vouchers. Existing clients can ignore the additive fields. No new API version is required. Balance and option costs are whole units, while savings and eligible spend are Money. Direct stamp options retain stamp_cost; point options and exchange descriptions use quantity_cost.
Kiosk and Online Ordering stamp and point balances include existing_redemptions, matching their existing voucher entries. Each entry contains a YQueue transaction uuid and a formatted monetary description. Only successful redemptions for that order and balance with a positive remaining net amount are included. The list remains available when a pool is empty, expired or archived, or its reward options change. Kiosk uses these transaction UUIDs with its existing reversal action; Online Ordering retains its existing cancellation/refund workflows. POS customer lookup remains independent of any order and does not expose this list.
All three services add igloox/stamps-redemption and igloox/points-redemption under their existing payment prefixes. Supply loyalty_balance_uuid, redemption_option_uuid and the customer's current redemption_pin. Only fixed and percentage monetary rewards are exposed. Current affordability is advisory; refresh discovery when an option is unavailable. Exchange descriptions remain discoverable, but these YQ APIs do not implement checkout exchange.
Kiosk and Online Ordering calculate savings and enforce stacking from their order. POS additionally supplies igloox_customer_uuid, eligible_spend and outstanding_balance, owns its cart calculation/stacking and attaches the returned transaction through associated_transactions. POS voucher redemption also accepts eligible_spend; order_subtotal remains a fallback when it is omitted. If both are supplied, eligible_spend wins.
Eligible spend is discounted item sale value after promotions and earlier monetary loyalty rewards, excluding taxes, charges, tips and top-ups. Stored value and offline vouchers are payments rather than reward discounts. Percentage rewards use the remaining eligible spend with half-up rounding and any cap, limited to the remaining payable amount. Every active voucher, stamp and point reward must permit stacking; failed and fully reversed rewards are excluded.
A direct reward consumes its complete unit cost even for a smaller allowed saving. Supported full reversals restore that original cost once before the receipt's original deadline, including after PIN/configuration changes or archival. Kiosk uses its existing reversal action; Online Ordering uses existing cancellation/full-refund workflows. POS adds POST /transactions/{uuid}/refund with monetary refund_amount, returning the updated transaction with HTTP 200. It permits same-outlet transactions from other devices and transactions not yet linked to an order. iglooX refunds are full-only; other gateways keep their existing rules. Payment cancellation remains ShopBack-only.
Kiosk and POS actions support cached successful idempotent replay. Online Ordering redemptions do not. After an uncertain checkout result, verify order/transaction/refund and customer balances before another attempt; there is no automatic provider reconciliation. Source purchase capture/void delivery retains its separate durable recovery. A source void does not itself undo checkout redemptions, and partial source refunds leave captured purchase loyalty unchanged.
Category attribution and SKU reporting
Kiosk order placement, POS line-item sync and Online Ordering cart requests accept optional source_category_name. Send the category used to select the item; the API stores the supplied name without looking up the current catalog. Cart and order line-item responses include the saved name, or null when unattributed. Existing orders have no category attribution.
When editing an OA cart line or syncing a POS line, omitting the field or sending null clears its attribution. Otherwise identical OA cart lines can still merge across categories; the first line's category wins, including null.
SKU and SKU summary reports accept catalog_type: category. They group by saved category name across different items, prices and selected outlets, without rolling up catalog parents. Quantity counts parent item units. Gross sales includes selected modifiers and meals before discounts, surcharges and taxes. Null is displayed as "Unattributed"; a category literally named "Unattributed" remains a separate group.
Category summaries contain Name, Quantity and Gross Sales, without Unit Price. Other summary modes retain their existing columns. Catalog renames and deletions do not change recorded attribution.
Order merging
POS can now sync order merges through the existing order-sync endpoint. The source orders are the orders being combined; the target order receives their combined items. Sources and targets can be uploaded separately and in either order.
Order responses include two nullable links:
merged_into_order_uuididentifies the direct target of a source order.merged_from_order_uuidsrecords the source orders combined into a target.
When syncing an existing order, omit a link field to keep its stored value. If you include it, send the complete value you want stored. POS must keep the full source UUID history when a target is merged again. Neither merge-link field may reference the order's own UUID, ignoring case. See Sync Orders for payloads, timestamp defaults and the eligibility and pricing rules POS must enforce.
Source orders remain available in history with cancelled_at and closed_off_at set. They also expose a merged event at every API version. Customer tracking displays "Merged" and "Please contact the merchant for more information." Payment and cancellation actions are hidden, and the source's authorization does not grant access to the target.
A payment can succeed before POS or the API learns that an order has been merged. Merge uploads remain accepted if this happens. The source stays merged and the transaction remains associated with that source; the merchant must reconcile it manually. Payments are not transferred to the target automatically.
Use collection_attributes.order_collection_identifier.value for free-form table input.
POS financial merge sync remains accepted. The iglooX layer resolves uncertain attempted captures before deciding loyalty merge safety. A quantity-evaluated source, including a frozen zero award, holds loyalty void/replacement processing for reconciliation; it is not repaired by void/re-capture. For non-evaluated sources, target submission waits for accepted constituent captures to be withdrawn.
Reporting changes
- Sales, order counts and item metrics include active dispatched orders and exclude cancelled orders and merged sources. Combined sales use the target's original
dispatched_at, even when the merge happens on a later day. - POS Sales Summary lists sources separately under
Merged (Orders). Cancellation and merge exceptions usecancelled_at. Historical searches and exports still include source orders. - Payment totals include all successful outlet payments, including those on cancelled or merged orders and those without an order. Payments and refunds belong to their own
finalised_atperiods; transaction-history entries without that date usecreated_at. - Refunds use the actual refund method. Refunding a card payment in cash reduces Cash Collected. Refund Count counts successful refund records, so two refunds against one payment count as two.
- POS Payment Total shows gross payments. Dashboard Payment Total, Total Collected and Cash Collected deduct refunds in the period they occur.
- Completed-order payment differences use balances at the report end. They include orders closed off in the period and earlier completed orders with payment or refund activity in the period.
- POS Sales Summary conditionally includes
Merged Orders with Paymentsfor sources merged by the report end that retain positive net payments and have merge or successful payment/refund activity in the period. Its breakdown shows retained net payments requiring manual reconciliation; fully refunded sources are omitted. - Payment Methods refund metrics omit methods without refund activity in the period. Payment-only methods no longer produce zero rows in those metrics.
- Transaction Summary amounts cover activity in the requested period, so a refund-only row can show Payment Amount $0, Refund Amount $4 and Total Collected -$4. Status and Payment Method describe the original transaction. Processed shows the latest included activity time for finalised transactions; unfinalised transactions display
-in the API table and an empty field in scheduled CSV exports. - GTO submissions retain successful payment and refund amounts, including any transaction counts the integration requires. Merged sources do not contribute order, receipt, item or adjustment figures.
For example, a $10 payment on Monday followed by a $4 refund on Tuesday contributes $10 to Monday's Total Collected and −$4 to Tuesday's. Across both days, POS Payment Total is $10 and net Total Collected is $6. See POS Sales Summary for the report contract.
POS floor plans
Linked POS terminals can retrieve published floor snapshots and retained deletion markers through Retrieve Floor Plans. Only the primary terminal can publish complete snapshots or deletion markers through Sync Floor Plans.
Floors use client-managed revisions: newer revisions replace the saved snapshot, while equal or lower revisions return the existing state. Omitted floors remain unchanged. Retained deletion markers prevent older snapshots from restoring a deleted floor; restoring it requires a higher revision.
Catalog sub-categories
Category responses now include an ordered sub_categories array of regular category UUIDs. Merchant Console and POS category create, edit and bulk-edit requests accept this field. Single edits replace the links or clear them with []; bulk edits append unique links. Omitting the field preserves links on edits and defaults to [] on creation.
Categories may be shared between parents and included directly in menus. Applications follow one level of links; the API rejects direct self-links but permits deeper links and indirect cycles. Responses remain flat and direct entries are unchanged, so older clients continue to see the same direct item lists. Product groups include only directly referenced categories' items.
29-10-2026
iglooX balance discovery and redemption
Kiosk and Online Ordering payment configurations return igloox: { enabled, login_required, stored_value, vouchers, stamps, points }. POS customer lookup returns { customer, stored_value, vouchers, stamps, points }. All three services support voucher discovery and redemption.
Stored-value entries are flat and use uuid for the customer balance. They expose balance, available_balance, state, is_usable, validity and minimum redemption, alongside the name and description. They no longer expose a loyalty-program UUID. Kiosk entries also include existing redemptions for that balance.
Use loyalty_balance_uuid in stored-value requests and the igloox/stored-value-redemption route at each service's existing payment prefix. Earlier response shapes and selector names remain available when explicitly selecting a supported older API version. The old igloox/redemption route is unavailable for 29-10-2026 and unversioned requests.
Online Ordering automatically redeems the lesser of the selected wallet's available balance and the order's outstanding balance. The wallet must be usable, match the order currency and provide an amount that meets the program's minimum redemption. Clients send loyalty_balance_uuid and redemption_pin, without a redemption_value. Refresh the order and payment configuration after redemption, then pay any remaining balance using another available method. Kiosk and POS stored-value requests still require an explicit redemption_value.
Online Ordering, Kiosk and POS expose igloox/voucher-redemption at each service's existing payment prefix. Requests identify the voucher with loyalty_balance_uuid and include redemption_pin; each successful call consumes one voucher. The server calculates fixed or percentage savings using the issued benefit, current program redemption rules and order context. Savings use discounted remaining eligible spend, half-up rounding and any percentage cap, limited to the remaining payable amount. Remaining amounts can be paid with another method. Existing full reversal restores one voucher; partial iglooX reversals remain unsupported.
Online Ordering and Kiosk derive the order amounts and enforce stacking across voucher, stamp and point discounts on the server. POS supplies igloox_customer_uuid, eligible_spend (or the compatibility order_subtotal fallback) and outstanding_balance, enforces stacking locally and attaches the returned server-managed transaction through associated_transactions during order sync.
Stored value, voucher, stamp and point suppression control their discovery independently; voucher suppression additionally hides quantity exchange descriptions. Suppression does not disable the latest API's membership login or order association, so an order can still be tracked by iglooX.
POS and Kiosk iglooX redemptions, Kiosk reversals and POS transaction refunds support cached successful idempotent replay. Online Ordering redemptions do not provide cached idempotent replay. iglooX provider failures are not automatically reconciled; verify the order and customer balances before reattempting after an uncertain outcome.
27-10-2026
Handle the merged order status
Update clients to recognise merged. If a client cannot handle this status yet, explicitly select a supported older version using X-API-VERSION.
| Version selection | Status returned for a merged source | What a cancelled filter includes |
|---|---|---|
27-10-2026 or newer, or no version header |
merged |
Genuine cancellations |
| An explicit older version | cancelled |
Genuine cancellations and merged sources |
Merge links, events and timestamps are returned at every version. Syncing cancelled for an existing merged source preserves the stored merged status at every API version, including requests without a version header. Existing merge timestamps are preserved when omitted or supplied as null.
Merchant Console and OMS order searches, and the Merchant Console order-summary report filter, accept merged. Historical report rows show the stored merged text at every version.
18-09-2026
Adds POS iglooX customer and stored-value support.
POS can now look up an iglooX customer by mobile number or customer UUID, discover their outlet- and tier-eligible loyalty programs and balances, and perform idempotent stored-value redemptions. POS outlet configuration now exposes integrations.igloox, including integration availability and the customer signup URL; the iglooX stored-value payment method is available only while that integration is enabled.
POS order sync accepts an optional igloox_customer_uuid, and order responses expose the effective association. Omitting the property or supplying null preserves any existing association. A customer UUID is accepted while the integration is disabled, but upstream submission is suppressed; replacements that conflict with existing iglooX redemption or submission state are silently ignored so offline synchronization can continue.
Renames iglooX campaigns to loyalty programs.
iglooX redemption requests now use loyalty_program_uuid. iglooX payment configurations now return loyalty_programs, with each entry exposing loyalty_program and loyalty_balance.
API versions up to and including 26-08-2026 retain the legacy campaign_uuid, campaigns, campaign and balance fields.
26-08-2026
Adds POS catalog management support.
Primary POS terminals can search and manage menus, categories, items, meals, modifier groups and modifiers, as well as search and retrieve existing media-library entries.
Bulk catalog retrieval now supports sorting by name or uuid and returns the complete matching catalog, including promo-code discounts. Older API versions retain the legacy bulk-retrieve contract: sorting is not supported and promo-code discounts are excluded. API versions older than 06-07-2026 also filter price override discounts.
06-07-2026
Adds support for price override discounts.
Clients using this version can receive and redeem discounts whose calculation type is price_override. Older API versions filter price override discounts from catalog responses and reject price override promo codes where the client cannot safely interpret them.
09-03-2026
Adds support for retail self-checkout kiosk integrations.