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 POST /merchant/v1/pos/activate.

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, always with HTTP 200.

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.

queueConfigurationobjectRequired

Object with queueUrl, region, accessKeyId, and secretAccessKey. The AWS credentials can only receive and delete messages on this POS 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

POS-side identifier of the tip recipient for this station. This is the same value as TipRecipient.externalTipRecipientId. OpenApp uses it 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 returned by GET /merchant/v1/tipRecipients, GET /merchant/v1/tipRecipients/{id}, and the tipRecipient field of PUT /merchant/v1/tipRecipients/{id} responses.

idstringRequired

OpenApp-generated identifier. The OpenApp app uses this value during confirmation. The POS should address the record by externalTipRecipientId instead.

merchantIdstringRequired

OpenApp merchant identifier associated with the API credential.

integrationProfileIdstringRequired

OpenApp integration-profile identifier associated with the API credential.

externalTipRecipientIdstringRequired

Stable POS-side identifier supplied as the {id} path parameter. This is the same value as tipRecipientId in payment messages and receipt QR codes.

displayNamestringRequired

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

linkStatusstringRequired

Current linking state. See Link status.

phoneNumberstringOptional

Normalized phone number submitted for linking. Present while linkStatus is PENDING and removed after confirmation.

expiresAtstringOptional

ISO 8601 confirmation deadline. Present while linkStatus is PENDING and removed after confirmation. OpenApp rejects confirmation after this time, but asynchronous record deletion may happen later.

linkedAtstringOptional

ISO 8601 timestamp at which the staff member confirmed the link. Present when linkStatus is ACTIVE.

Tip-recipient linking messages​

PutTipRecipientRequest​

Request body for PUT /merchant/v1/tipRecipients/{id}. The {id} path parameter becomes the record's externalTipRecipientId.

phoneNumberstringRequired

Phone number the staff member wants to link, in E.164 format (for example +48123456789). The staff member may already have an OpenApp account or may create one later.

displayNamestringRequired

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

LinkTipRecipientResponse​

Returned by PUT /merchant/v1/tipRecipients/{id} after OpenApp creates or updates the record.

tipRecipientTipRecipientRequired

Resulting TipRecipient record. Its linkStatus can be PENDING or ACTIVE, depending on the record's previous state and the submitted phone number.

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

ValueMeaning
PENDINGOpenApp accepted the submission, but the staff member has not confirmed it. The record has a confirmation deadline in expiresAt.
ACTIVEThe staff member confirmed the link and passed the OpenApp KYC requirement. Tips attributed to externalTipRecipientId go to their OpenApp wallet.