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.

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 station (table) ordering active.

STATION availability gates table ordering only.

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 STATION, 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 station or order. See orderContext.

checkpointstringOptional

The latest POS-side state checkpoint OpenApp holds. For table-session contexts, this is the updatedAt from the most recent tableOrderSnapshot; the POS uses it to decide whether to return ORDER_CHANGED. Omitted for stateless flows such as Scan & Pay where OpenApp holds no prior state. ISO 8601 timestamp.

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.

billobjectRequired

See bill.

tipRecipientIdstringOptional

Identifier of the tip recipient for this station. Returned when the POS can identify who should receive the tip. OpenApp uses this to attribute tips. When the customer scanned a receipt QR with a tip recipient embedded (see Scan & Pay - Building the receipt QR), that value takes precedence and this field is ignored.

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.bill.

billingDetailsobjectOptional

Invoice data. See billingDetails.

BillPaymentFailed​

Sent only when OpenApp payment fails after a successful BillPreparationResult.

posBillIdstringRequired

POS-assigned identifier returned in BillPreparationResult.bill.

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

STATION. Station order context - covers both table and kiosk stations.

stationIdstringRequired

POS station identifier resolved by OpenApp from the station QR.

stationKindstringRequired

Station kind. TABLE for a table station; KIOSK for a kiosk station.

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.

linesarrayOptional

Bill lines as frozen by the POS. Optional - the POS may return a total-only bill when itemized line data is unavailable or not required. TBD

totalsobjectRequired

Bill totals. TBD

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.

TipRecipient​

A tip-recipient record as stored on the OpenApp side. Returned by GET /tip-recipients, GET /tip-recipients/:id, and PUT /tip-recipients/:id.

tipRecipientIdstringRequired

Stable POS-side identifier for this tip recipient. Matches the tipRecipientId carried in the receipt QR and BillPreparationResult.

displayNamestringRequired

Human-readable name of the tip recipient as shown to staff.

statusstringRequired

Current linking state. See Link status.

expiresAtstringOptional

ISO 8601 timestamp after which a pending submission is silently discarded. Present only when status is PENDING.

Tip-recipient linking messages​

PutTipRecipientRequest​

Request body for PUT /tip-recipients/:id. Upserts the tip-recipient record and initiates account linking in a single call.

phoneNumberstringRequired

OpenApp phone number of the staff member, in E.164 format (for example +48123456789). The staff member may already have an OpenApp account or may not yet - both are valid.

displayNamestringRequired

Human-readable name of the tip recipient. Creates or updates the record's display name.

LinkTipRecipientResponse​

Returned by OpenApp in response to LinkTipRecipient.

successbooleanRequired

true. The submission was accepted and the association is pending confirmation.

statusstringRequired

PENDING. The association has been stored and OpenApp is handling the confirmation flow.

expiresAtstringRequired

ISO 8601 timestamp after which a pending submission is silently discarded.

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
NO_OPEN_BILLNo open or payable bill exists for the scanned station. For kiosk stations, OpenApp may offer the self-order (K2) path in response.
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
STATIONStation order context (table or kiosk).
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.

Used by TipRecipient.status.

ValueMeaning
PENDINGA linking submission was accepted; the staff member has not yet confirmed or completed KYC.
ACTIVEThe staff member confirmed the link and their KYC is active. Tips attributed to this tipRecipientId are routed to their OpenApp wallet.

Linking rejection reasons​

Used by LinkTipRecipientResponse.reasonCode.

ReasonMeaning
PHONE_FORMAT_INVALIDThe phone number is not in valid E.164 format.
PHONE_ALREADY_LINKEDThe phone number is already linked to a different tipRecipientId for this location.