Skip to main content

Data Models

This page is the reference for all POS integration message payloads, shared base models, and enums.

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.

softwareNamestringRequired

POS software product name.

softwareVersionstringRequired

POS software version string.

PosActivationResponse​

Returned by OpenApp in response to ActivatePos.

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.

ReportPosHealth​

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

If OpenApp does not receive health checks within the timeout configured on the integration profile, OpenApp marks the POS capability unavailable, stops sending POS-backed ordering commands, and tells customers that the location is currently unavailable.

healthybooleanRequired

Current POS health status.

softwareNamestringRequired

POS software product name.

softwareVersionstringRequired

POS software version string.

Availability control messages​

PosLocationAvailabilityChanged​

Pushed by the POS when the location is opened or closed for OpenApp-backed ordering. Closing the location disables new table, pickup, and delivery ordering until the POS opens it again or OpenApp receives an equivalent availability update from another authorized source.

openbooleanRequired

true when the location is open for OpenApp-backed ordering; false when closed.

reasonCodestringOptional

Machine-readable reason, for example CLOSED_FOR_DAY, TEMPORARILY_CLOSED, or POS_OPERATOR_ACTION.

messagestringOptional

Human-readable message that OpenApp may map to customer-facing copy.

effectiveAtstringOptional

ISO 8601 timestamp when the state becomes effective. Defaults to receipt time.

PosOrderTypeAvailabilityChanged​

Pushed by the POS when it wants to change availability for selected OpenApp-backed order types without closing the location. This supports temporary capacity controls, for example pausing pickup and delivery during rush hours while keeping table ordering active.

changesarray of objectsRequired

List of order-type availability changes. Only the listed order types change; omitted types are left as-is. Each item contains orderType, state, optional reasonCode, and optional effectiveUntil.

Show child parametersHide child parameters4
orderTypeOrderTypeRequired

Order type to change. See Order types.

stateOrderTypeAvailabilityStateRequired

Desired state for this order type. See Order type availability states.

reasonCodestringOptional

Machine-readable reason for this order-type state, for example KITCHEN_OVERLOADED, NO_DRIVERS.

effectiveUntilstringOptional

ISO 8601 timestamp after which OpenApp may clear this order-type state. If omitted, the state remains until changed.

Example:

{
  "changes": [
    {
      "orderType": "PICKUP",
      "state": "PAUSED",
      "reasonCode": "KITCHEN_OVERLOADED",
      "effectiveUntil": "2026-05-29T18:00:00Z"
    },
    {
      "orderType": "DELIVERY",
      "state": "PAUSED",
      "reasonCode": "NO_DRIVERS",
      "effectiveUntil": "2026-05-29T19:00:00Z"
    }
  ]
}

ProductListingsSyncRequested​

checkpointobject | nullRequired

Last synchronization checkpoint. null requests a full sync. An object 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.

successbooleanRequired

true.

tableSessionContextobjectRequired

See tableSessionContext.

tableOrderSnapshotobjectRequired

See tableOrderSnapshot.

OrderSubmissionRequested​

Submits items for a TABLE, PICKUP, or DELIVERY fulfillment context.

When payment is present, OpenApp has already completed the customer payment and the submission is prepaid. When payment is omitted, the submission is unpaid/postpaid and payment is handled later outside this message.

orderContextobjectRequired

See orderContext.

itemsarrayRequired

Items being submitted to the POS. TBD

paymentobjectOptional

Completed OpenApp payment for prepaid submissions. Omit for unpaid/postpaid submissions. See payment.

OrderSubmissionResult​

Returned by the POS in response to OrderSubmissionRequested. Used by table, pickup, and delivery contexts.

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

successbooleanRequired

true. All submitted items were accepted.

acceptedItemsarrayRequired

Items the POS accepted. TBD

tableOrderSnapshotobjectOptional

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

receiptobjectOptional

Receipt or fiscal confirmation for prepaid submissions where OrderSubmissionRequested.payment was present. See receipt.

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​

BillPreparationRequested​

orderContextobjectRequired

Identifies the table or order. See orderContext.

checkpointstringRequired

The latest POS-side state checkpoint OpenApp holds. For table contexts, this is the updatedAt from the most recent tableOrderSnapshot. 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 order is being paid. References existing POS-side line identifiers from tableOrderSnapshot.lines. Selector format is TBD alongside the line-identifier schema on tableOrderSnapshot.lines.

BillPreparationResult​

Returned by the POS in response to BillPreparationRequested.

successbooleanRequired

true.

posBillIdstringRequired

POS-assigned identifier for the prepared bill.

billobjectRequired

See bill.

BillPaymentCompleted​

Used when OpenApp payment happens after the POS has prepared a bill.

paymentobjectRequired

Payment details to record. See payment.

posBillIdstringRequired

POS-assigned identifier returned in BillPreparationResult.

BillPaymentFailed​

Sent only when OpenApp payment fails after a successful BillPreparationResult.

posBillIdstringRequired

POS-assigned identifier returned in BillPreparationResult.

reasonCodestringRequired

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

BillPaymentResult​

Returned by the POS in response to BillPaymentCompleted for later OpenApp payment against a prepared bill.

successbooleanRequired

true.

receiptobjectRequired

See receipt.

Base models​

orderContext​

Identifies the POS-side fulfillment context that a command applies to.

typestringRequired

TABLE. Table order context.

tableIdstringRequired

POS table identifier.

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​

Successful OpenApp payment details. 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 after the POS records or 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.

ValueMeaning
OPENTable is open and accepting changes.
CLOSINGTable is being closed; mutations may be rejected.
CLOSEDTable is closed.
CANCELLEDTable was cancelled.

Mutation rejection reasons​

Used by OrderSubmissionResult.rejectedItems[].reasonCode.

ReasonMeaning
OUT_OF_STOCKItem is no longer available.
INSUFFICIENT_STOCKRequested quantity is unavailable.
DELISTEDItem no longer exists or cannot be sold.
ORDER_CLOSEDTable or check is closed or closing.
PRICE_CHANGEDOpenApp must refresh the price or listing snapshot.

Change types​

Used by TableOrderSnapshotChanged.changeType.

ValueUse Case
POS_LINE_ADDEDWaiter adds drinks or food directly in the POS.
LINE_CANCELLEDKitchen or POS cancels a line, for example out of stock.
LINE_DELIVEREDWaiter marks drinks or food as delivered.
LINE_UPDATEDWaiter removes or discounts a line after a complaint.
ORDER_CLOSEDPOS closes the table or open order.

Bill preparation rejection reasons​

Used by BillPreparationResult.reasonCode.

ReasonMeaning
ORDER_CHANGEDPOS revision changed; OpenApp must refresh and reconfirm with the customer.
ORDER_CLOSEDBill or order is already closed.
PAYMENT_NOT_ALLOWEDPOS cannot accept an OpenApp payment for this table or order.
FISCAL_ERRORFiscalization or receipt preparation failed.
POS_OFFLINE_OR_BUSYTemporary POS failure.

Activation failure reasons​

Used by PosActivationResponse.failureReason.

ReasonMeaning
INVALID_OR_EXPIRED_PINPIN does not exist, has expired, was already consumed, or does not match the submitted merchantTaxId.
ACTIVATION_NOT_ALLOWEDThe merchant, integration profile, location, or POS capability is not in a state that allows activation.

Order types​

Used by PosOrderTypeAvailabilityChanged.changes[].orderType.

ValueMeaning
TABLETable order context.
PICKUPIn-person pickup context.
DELIVERYDelivery context.

Order type availability states​

Used by PosOrderTypeAvailabilityChanged.changes[].state.

ValueMeaning
ACCEPTINGOpenApp may start new orders of the type.
PAUSEDOpenApp must not start new orders of the type.