Queue Communication
Queue delivery is intended for POS systems that cannot receive inbound OpenApp HTTP calls.
OpenApp owns and manages the queue. The POS system receives queue credentials scoped to one POS integration capability. The POS polls the queue, processes retrieved messages, sends operation results to OpenApp through HTTP callbacks, and deletes messages from the queue after successful processing.
Queue consumers should use long polling. Long polling reduces empty polling, lowers unnecessary network traffic, and avoids latency caused by repeated short polling. The POS should poll continuously while the integration is active.
Queue delivery is at-least-once. The same message can be delivered more than once, so the POS must deduplicate commands using message identifiers and idempotency keys.
Queue delivery is FIFO within an ordering key. Table messages use tableId as the ordering key. Pickup and delivery messages use the order context key. Product listing sync messages use a constant ordering key such as catalog. Messages with the same ordering key are delivered in the order OpenApp sent them.
General queue flow:
Queue Message Envelope
OpenApp-initiated queue messages use a common envelope. The envelope is present in message attributes or in the message body.
| Field | Description |
|---|---|
| messageType | Logical message name used to route and deserialize the message. |
| apiVersion | Version of the API used for this message. |
| messageId | Unique message ID used for delivery deduplication and asynchronous response correlation. |
| idempotencyKey | Business-level deduplication key. Retries of the same business operation must reuse the same value. |
| payload | Message-specific payload. |
For request/response flows over queue delivery, OpenApp uses messageId for request correlation. After processing a queued command, the POS sends the result to the asynchronous callback endpoint for that message type:
POST /merchant/v1/async/{messageType}/{messageId}
The callback body contains the operation-specific result payload. The exact payload shape depends on the message type.
Message Correlation And Idempotency
Every OpenApp-initiated business command will have a unique message identifier for delivery deduplication and asynchronous response correlation.
Retries of the same business operation will reuse the same idempotency key. The POS should return the same business result for duplicated commands where possible.
POS-initiated events should also include a unique message identifier so OpenApp can deduplicate repeated event delivery.