Data Models

This page is the canonical reference for all POS integration message payloads, shared base models, and enums. Flow pages link to the anchors here.

Models marked TBD are not yet finalized in the integration contract and may change before general availability.

Activation messages

ActivatePos

Sent by the POS to activate against OpenApp.

merchantTaxIdstringRequired

Universal merchant tax identifier (for example, Polish NIP).

pinCodestringRequired

Short-lived activation PIN displayed in the merchant panel.

posInstallationIdstringOptional

Stable identifier for the POS installation on the merchant side.

softwareVersionstringOptional

POS software version string.

PosActivationResponse

Returned by OpenApp in response to ActivatePos.

Success

successbooleanRequired

true.

merchantIdstringRequired

Merchant identifier resolved from the merchantTaxId.

integrationProfileIdstringRequired

Location-scoped integration profile the POS is now bound to.

locationIdstringRequired

Physical location identifier.

posIdstringRequired

OpenApp-assigned POS identifier.

apiConfigurationobjectRequired

Object with credentials (apiKey, secret) used to sign POS-to-OpenApp calls.

queueConfigurationobjectOptional

Present only when queue delivery is configured. Contains queue URL, region, and AWS credentials scoped to the POS capability queue.

Failure

successbooleanRequired

false.

failureReasonstringRequired

See Activation failure reasons.

ReportPosHealth

Sent by the POS immediately after activation and at regular heartbeat intervals. OpenApp responds with HTTP 204 No Content.

healthybooleanRequired

Current POS health status.

softwareVersionstringOptional

POS software version string.

Menu sync messages

ProductListingsSyncRequested

checkpointobjectRequired

Last synchronization checkpoint. An empty checkpoint requests a full sync. Contains the timestamp of the last successful retrieval and the last seen POS listing identifier.

ProductListingsSynced

checkpointobjectRequired

Next checkpoint to use for subsequent incremental syncs.

listingsarrayRequired

Product listings changed after the requested checkpoint. Empty when nothing has changed.

ProductListingsUpdated

listingsarrayRequired

Changed product listing, price, or stock data. Contains only the diff.

Table ordering messages

TableOrderSnapshotRequested

tableIdstringRequired

POS table identifier resolved by OpenApp from the QR.

checkpointstringOptional

Last POS update timestamp stored by OpenApp for this table. The POS may use it to decide whether to return a snapshot.

TableOrderSnapshotResolutionResult

Returned by the POS in response to TableOrderSnapshotRequested.

Success

successbooleanRequired

true.

tableSessionContextobjectRequired

See tableSessionContext.

tableOrderSnapshotobjectRequired

See tableOrderSnapshot.

Failure

successbooleanRequired

false.

reasonCodestringRequired

Machine-readable rejection reason.

retryablebooleanRequired

Whether OpenApp may retry the request.

messagestringOptional

Human-readable description of the rejection.

currentStatusstringOptional

Current table status if known. See Table status.

OrderItemsSubmittedToPos

Used by both table ordering and prepaid pickup/delivery flows.

orderContextobjectRequired

See orderContext.

itemsarrayRequired

Items being submitted to the POS. TBD

OrderMutationResult

Returned by the POS in response to OrderItemsSubmittedToPos. Used by both table ordering and pickup/delivery flows.

success: false is also used when only some items were rejected.

Success

successbooleanRequired

true. All submitted items were accepted.

acceptedItemsarrayRequired

Items the POS accepted. TBD

tableOrderSnapshotobjectOptional

Updated POS table snapshot. Table flow only. See tableOrderSnapshot.

Failure

successbooleanRequired

false. At least one item was rejected.

acceptedItemsarrayOptional

Items the POS accepted, if any. TBD

rejectedItemsarrayRequired

Items the POS rejected, each with a reasonCode. See Mutation rejection reasons. TBD

tableOrderSnapshotobjectOptional

Updated POS table snapshot. Table flow only. See tableOrderSnapshot.

TableOrderSnapshotChanged

Pushed by the POS when the table order state changes on the POS side.

changeTypestringRequired

See Change types.

diffobjectRequired

Changed order lines, removed line identifiers, and status changes since the previous snapshot. TBD

reasonCodestringOptional

Required when the change has a business reason. For example out of stock, complaint, or POS-side cancellation.

Bill and payment messages

BillRequested

orderContextobjectRequired

Identifies the table or order. See orderContext.

checkpointstringRequired

The updatedAt from the most recent tableOrderSnapshot OpenApp holds for this table. The POS uses it to decide whether to return ORDER_CHANGED because its state has moved on. ISO 8601 timestamp.

billingDetailsobjectOptional

Invoice data if the customer requested an invoice. See billingDetails.

itemsarrayOptional

Items to bill. Present when only a subset of the table is being paid.

BillPreparationResult

Returned by the POS in response to BillRequested.

Success

successbooleanRequired

true.

posBillIdstringRequired

POS-assigned identifier for the prepared bill.

billobjectRequired

See bill.

Failure

successbooleanRequired

false.

reasonCodestringRequired

See Bill preparation rejection reasons.

retryablebooleanRequired

Whether OpenApp may retry the request.

currentSnapshotobjectOptional

Current POS table snapshot if available. See tableOrderSnapshot.

PaymentCompleted

Used by both table-postpay and prepaid pickup/delivery flows.

paymentobjectRequired

Payment details to record. See payment.

posBillIdstringOptional

POS-assigned identifier returned in BillPreparationResult. Required for the table flow; absent for prepaid pickup/delivery (no BillPreparationResult was issued).

PaymentFailed

Sent only for the table-postpay flow. Prepaid pickup/delivery never triggers PaymentFailed because OpenApp executes payment before contacting the POS — if it fails, OpenApp does not call the POS at all.

posBillIdstringRequired

POS-assigned identifier returned in BillPreparationResult.

reasonCodestringRequired

Machine-readable failure reason. The POS releases any prepared or payment-pending state.

PosPaymentResult

Returned by the POS in response to PaymentCompleted. Used by both table-postpay and prepaid pickup/delivery flows.

Success

successbooleanRequired

true.

posBillIdstringOptional

POS-assigned identifier the payment was applied to. Table flow only.

oaPaymentIdstringRequired

The OpenApp payment identifier from PaymentCompleted.payment.

receiptobjectRequired

See receipt.

Failure

successbooleanRequired

false. OpenApp refunds the OpenApp payment.

posBillIdstringOptional

POS-assigned identifier the payment targeted. Table flow only.

oaPaymentIdstringRequired

The OpenApp payment identifier from PaymentCompleted.payment.

reasonCodestringRequired

Machine-readable rejection reason.

retryablebooleanRequired

Whether OpenApp may retry applying the payment.

Base models

orderContext

Identifies the POS-side context that a command applies to. PICKUP and DELIVERY are prepaid: OpenApp executes payment before submitting to the POS.

Table

typestringRequired

TABLE. Table QR order. Payment applied to POS bill.

tableIdstringRequired

POS table identifier.

customerNotestringOptional

Free-text note visible to the POS.

Pickup

typestringRequired

PICKUP. Prepaid in-person pickup order.

pickupDetailsobjectRequired

Pickup details. TBD

customerNotestringOptional

Free-text note visible to the POS.

Delivery

typestringRequired

DELIVERY. Prepaid delivery order.

deliveryDetailsobjectRequired

Delivery details (address, contact, courier hint). TBD

customerNotestringOptional

Free-text note visible to the POS.

tableSessionContext

Table session metadata returned alongside table snapshots when the table is resolved.

locationIdstringRequired

Physical restaurant location.

tableIdstringRequired

POS table identifier.

tableNumberstringRequired

Human-readable table number.

statusstringRequired

See Table status.

openedAtstringRequired

ISO 8601 timestamp the table was opened.

closedAtstringOptional

ISO 8601 timestamp the table was closed. Present when status is closed or cancelled.

tableOrderSnapshot

The POS remains the source of truth for table/open-check state. OpenApp maps relevant state into customer-facing views.

tableIdstringRequired

POS table identifier.

statusstringRequired

See Table status.

linesarrayRequired

POS order lines. TBD

totalsobjectRequired

Bill totals. TBD

paymentsarrayRequired

POS-applied payments. TBD

updatedAtstringRequired

ISO 8601 timestamp of the last POS update. Used by OpenApp as the next sync checkpoint.

billingDetails

Invoice data attached to a bill when the customer requests an invoice. TBD

taxIdstringRequired

Tax identifier of the entity being billed (for example, Polish NIP).

companyNamestringRequired

Legal name on the invoice.

addressobjectRequired

Postal address. TBD

bill

Returned by the POS in BillPreparationResult when the bill is prepared. TBD

posBillIdstringRequired

POS-assigned identifier for the prepared bill.

linesarrayRequired

Bill lines as frozen by the POS. TBD

totalsobjectRequired

Bill totals. TBD

billingDetailsobjectOptional

See billingDetails.

preparedAtstringRequired

ISO 8601 timestamp the bill was prepared and frozen.

payment

Sent by OpenApp in PaymentCompleted to record a successful OpenApp payment. TBD

oaPaymentIdstringRequired

OpenApp payment identifier.

amountobjectRequired

Money object with value (integer, minor units) and currency (string). TBD

paidAtstringRequired

ISO 8601 timestamp the payment was completed.

receipt

Returned by the POS in PosPaymentResult after the POS applies the OpenApp payment. TBD

receiptNumberstringRequired

POS-assigned receipt number.

fiscalSignaturestringOptional

Fiscalization signature if applicable.

issuedAtstringRequired

ISO 8601 timestamp the receipt was issued.

receiptUrlstringOptional

URL where the receipt can be retrieved.

Enums

Table status

Used by tableSessionContext.status and tableOrderSnapshot.status.

Value	Meaning
OPEN	Table is open and accepting changes.
CLOSING	Table is being closed; mutations may be rejected.
CLOSED	Table is closed.
CANCELLED	Table was cancelled.

Mutation rejection reasons

Used by OrderMutationResult.rejectedItems[].reasonCode.

Reason	Meaning
OUT_OF_STOCK	Item is no longer available.
INSUFFICIENT_STOCK	Requested quantity is unavailable.
DELISTED	Item no longer exists or cannot be sold.
ORDER_CLOSED	Table or check is closed or closing.
PRICE_CHANGED	OpenApp must refresh the price or listing snapshot.

Change types

Used by TableOrderSnapshotChanged.changeType.

Value	Use Case
POS_LINE_ADDED	Waiter adds drinks or food directly in the POS.
LINE_CANCELLED	Kitchen or POS cancels a line, for example out of stock.
LINE_DELIVERED	Waiter marks drinks or food as delivered.
LINE_UPDATED	Waiter removes or discounts a line after a complaint.
ORDER_CLOSED	POS closes the table or open order.

Bill preparation rejection reasons

Used by BillPreparationResult.reasonCode.

Reason	Meaning
ORDER_CHANGED	POS revision changed; OpenApp must refresh and reconfirm with the customer.
ORDER_CLOSED	Bill or order is already closed.
PAYMENT_NOT_ALLOWED	POS cannot accept an OpenApp payment for this table or order.
FISCAL_ERROR	Fiscalization or receipt preparation failed.
POS_OFFLINE_OR_BUSY	Temporary POS failure.

Activation failure reasons

Used by PosActivationResponse.failureReason.

Reason	Meaning
INVALID_OR_EXPIRED_PIN	PIN does not exist, has expired, was already consumed, or does not match the submitted merchantTaxId.
ACTIVATION_NOT_ALLOWED	The merchant, integration profile, location, or POS capability is not in a state that allows activation.