Integrate Real-Time Order State Changes with AWS Kinesis in Shift4 Venue

Description: Learn how to integrate Shift4 Venue with your AWS-hosted Kinesis stream to receive real-time order state changes. This guide covers infrastructure setup, permissions configuration, payload structure, field definitions, and data processing best practices.

Kinesis Feed Overview

Shift4 Venue’s ordering system publishes order state change events to a Kinesis stream hosted in Shift4 Venue’s AWS account. A Shift4 Venue-managed Lambda then publishes those messages to a Kinesis stream in your AWS account, which you must configure.

From there, you can connect your own Lambda functions to this stream to implement custom business logic.

This design provides full control over business logic and scaling capabilities, such as Kinesis shard counts, within your AWS environment.

Controlling Access

To enable Shift4 Venue’s Lambda to publish to your Kinesis stream, set up the following:

1. Create a Kinesis Writer IAM role in your AWS account.
2. Configure the role’s trust policy to trust the ARN of the Shift4 Venue Lambda role.

Example pseudocode:

credentials = Aws::AssumeRoleCredentials.new(
  role_arn: "THE-ARN-OF-THE-WRITER-ROLE-YOU-CREATED"
)

kinesis_client = Aws::Kinesis::Client.new(credentials)

kinesis_client.put_record(
  stream_name: "your-stream-name",
  data: <JSON PAYLOAD HERE>
)

Shift4 Venue’s Lambda will assume the role you provide, enabling it to publish to your stream.

Implementation Order

1. You create:
   • A Kinesis stream in your AWS account
   • A Kinesis Writer IAM role (leave the trust policy empty for now)
   • Provide Shift4 Venue with:
     • The ARN of the writer role
     • The AWS region of the stream
2. Shift4 Venue will:
   • Provision a Lambda that publishes to your Kinesis stream
   • Share the ARN of the Lambda role
3. You update:
   • The trust policy of your writer role to allow the Shift4 Venue Lambda to assume it

Shift4 Venue Integration

Shift4 Venue’s ordering system, Stadium, emits order state change events. These are published to your Kinesis stream through the integration Lambda. Your own AWS-hosted Lambdas can consume and process these events.

Requirements

Shift4 Venue

• A Kinesis stream per environment (for example, mars-dev or levis-prd)
• A dedicated publishing Lambda

Client

• A Kinesis stream
• A consumer Lambda with required business logic
• IAM roles with appropriate read/write permissions

Identity Management / Permissions

Set up the following AWS resources:

• A Kinesis stream
• A consumer Lambda with logic to process messages
• An IAM role/user for the Lambda with permission to read from the stream
• A Writer Role with sts:AssumeRole permissions for the Shift4 Venue Lambda ARN

Sample Payload

The following example illustrates an order.state.change event. Fields may contain null or empty values depending on the order, payment method, device, and integration configuration.

{
  "_id": "01k59tjjnmmssyj9n16eq91ykp",
  "_v": 1,
  "o": "arena",
  "u": "03f27d37-1b3c-4e1e-bc06-00d2634c1a11",
  "s": "stadium",
  "e": "order.state.change",
  "p": {
    "bundle_id": null,
    "client_created_at": "2026-07-21T17:56:12Z",
    "confirmation_number": "1606013",
    "created_at": "2026-07-21T17:56:13Z",
    "device_uuid": "2210067994",
    "discount": "0",
    "device_subtype": "concessions-pos",
    "employee_id": "2adaebb3-3538-4cb0-992c-ff7f54d504f9",
    "employee_name": "Testing Testing",
    "menu_external_ref_id": null,
    "menu_name": "UPLOAD-ST 101 Stadium Snacks Shack - POS",
    "product_type": "Food",
    "revenue_center_external_ref_id": "st_101_stadium_snacks_shack",
    "revenue_center_name": "UPLOAD-ST 101 Stadium Snacks Shack",
    "revenue_center_uuid": "c9069452-2832-4217-ba58-e6290fbdc7d3",
    "sales_event_id": null,
    "service_type": "POS",
    "source_device_uuid": "2210067994",
    "state": "authorization_failed",
    "tax": 0,
    "tip": 80,
    "total": 4080,
    "transaction_history": [
      {
        "state": "authorized",
        "time": "2026-07-21T17:56:15Z"
      }
    ],
    "updated_at": "2026-07-21T17:56:15Z",
    "user_attributes": {
      "last_4": "",
      "freedompay_merchant_reference_code": "25422afa-c753-405a-9f08-5146137cecc2",
      "freedompay_invoice_number": "1606089372",
      "is_card_present_transaction": false,
      "device_id": "2210067994",
      "internal_payment_type": null,
      "related_invoice_numbers": [
        "1606089372"
      ],
      "line_item_tax_in_cents": {}
    },
    "user_external_ref_id": "03f27d37-1b3c-4e1e-bc06-00d2634c1a11",
    "uuid": "25422afa-c753-405a-9f08-5146137cecc2",
    "venue_uuid": "1c7a17e6-141a-4591-a59b-10c8f58d5584",
    "state_history": [
      {
        "state": "submitted",
        "time": "2026-07-21T17:56:12Z"
      },
      {
        "state": "authorization_failed",
        "time": "2026-07-21T17:56:13Z"
      }
    ],
    "line_items": [
      {
        "created_at": "2026-07-21T17:56:13Z",
        "modified_line_item_uuid": null,
        "name": "N-Cheeseburger",
        "price": 1000,
        "promotion_discount": 0,
        "promotions": [],
        "quantity": 1,
        "refunded_at": null,
        "removed_at": null,
        "reporting_category_uuid": "a8d361a5-4804-49f4-8ec6-7268a87004a5",
        "sku": "CHB-789",
        "tax_amount_in_cents": 0,
        "tax_inclusive": true,
        "type": null,
        "updated_at": "2026-07-21T17:56:13Z",
        "uuid": "e2147e52-19c8-4cc5-ae47-cc548b34e0eb"
      }
    ],
    "payment_transactions": [
      {
        "authorization_amount": "0.0",
        "card_type": null,
        "created_at": "2026-07-21T17:56:15Z",
        "last_four": "",
        "payment_type": "shift4_credit",
        "settlement_amount": "0.0",
        "tip": 80,
        "updated_at": "2026-07-21T17:56:15Z",
        "type": "SalePaymentTransaction",
        "status": "authorized"
      }
    ]
  }
}

Data Types

The following describes the fields and data types represented in the Kinesis payload. Fields that are not applicable to a particular order or transaction may be null.

{
  "_id": "standard ULID string",
  "_v": "short integer",
  "o": "256 character string",
  "u": "36 character UUID",
  "s": "short string, currently always 'stadium'",
  "e": "256 character string",
  "p": {
    "bundle_id": "256 character string or null",
    "client_created_at": "256 character date string",
    "confirmation_number": "string",
    "created_at": "256 character date string",
    "device_uuid": "device identifier string",
    "discount": "256 character string discount amount",
    "device_subtype": "256 character string",
    "employee_id": "256 character string",
    "employee_name": "256 character string",
    "menu_external_ref_id": "256 character string or null",
    "menu_name": "256 character string",
    "product_type": "256 character string",
    "revenue_center_external_ref_id": "256 character string",
    "revenue_center_name": "256 character string",
    "revenue_center_uuid": "36 character UUID",
    "sales_event_id": "36 character UUID or null",
    "service_type": "short string",
    "source_device_uuid": "device identifier string",
    "state": "256 character string",
    "tax": "16-bit integer tax in cents",
    "tip": "16-bit integer tip in cents",
    "total": "16-bit integer total in cents",

    "transaction_history": [
      {
        "state": "256 character string",
        "time": "256 character date string"
      }
    ],

    "updated_at": "256 character date string",

    "user_attributes": {
      "last_4": "string",
      "freedompay_merchant_reference_code": "string",
      "freedompay_invoice_number": "string",
      "is_card_present_transaction": "boolean (true/false)",
      "device_id": "string",
      "internal_payment_type": "string or null",
      "related_invoice_numbers": [
        "string"
      ],
      "line_item_tax_in_cents": "object"
    },

    "user_external_ref_id": "256 character string",
    "uuid": "36 character UUID string",
    "venue_uuid": "36 character UUID string",

    "state_history": [
      {
        "state": "256 character string",
        "time": "256 character date string"
      }
    ],

    "line_items": [
      {
        "uuid": "36 character UUID string",
        "name": "256 character string",
        "price": "16-bit integer price in cents",
        "promotion_discount": "16-bit integer total in cents",
        "promotions": "array",
        "quantity": "16-bit integer",
        "sku": "256 character string",
        "created_at": "256 character date string",
        "updated_at": "256 character date string",
        "refunded_at": "256 character date string or null",
        "removed_at": "256 character date string or null",
        "modified_line_item_uuid": "36 character UUID string or null",
        "reporting_category_uuid": "36 character UUID or null",
        "tax_amount_in_cents": "16-bit integer tax in cents",
        "tax_inclusive": "boolean (true/false)",
        "type": "string or null"
      }
    ],

    "payment_transactions": [
      {
        "authorization_amount": "string amount",
        "card_type": "256 character string or null",
        "created_at": "256 character date string",
        "last_four": "4 character string, empty string, or null",
        "payment_type": "256 character string",
        "settlement_amount": "string amount",
        "tip": "integer tip amount in cents",
        "updated_at": "256 character date string",
        "type": "256 character string",
        "status": "256 character string"
      }
    ]
  }
}

Payload Deduplication Tip

Each payload includes a state_history array with timestamps. To detect duplicate messages:

• Sort the array by date.
• Generate a hash from the sorted array.
• Compare hashes to identify duplicates.

Kinesis Feed Field Reference

General Fields

• _id: Unique ULID identifier for the event.
• _v: Event schema version.
• o: Organization identifier.
• u: User UUID associated with the event.
• s: Event source. Currently "stadium".
• e: Event type. For order state changes, "order.state.change".

Order Object (p)

• uuid: Unique order ID.
• venue_uuid: Venue ID.
• confirmation_number: Human-readable order confirmation number.
• state: Current state of the order.
• client_created_at: Timestamp when the order was initiated by the client.
• created_at: Order creation timestamp.
• updated_at: Timestamp of the most recent order update.
• bundle_id: Bundle identifier, when applicable.
• device_uuid: Device identifier associated with the order.
• source_device_uuid: Identifier for the device from which the order originated.
• device_subtype: Device type or subtype, such as concessions-pos.
• total: Order total in cents.
• tax: Tax amount in cents.
• tip: Tip amount in cents.
• discount: Discount amount.
• revenue_center_name: Revenue center/location name.
• revenue_center_uuid: Revenue center/location ID.
• revenue_center_external_ref_id: External reference ID for the revenue center.
• menu_name: Menu name.
• menu_external_ref_id: External menu identifier, when available.
• service_type: Service type, such as POS or Delivery.
• product_type: Product category associated with the order.
• sales_event_id: Sales event identifier, when applicable.
• employee_name: Employee name, when applicable.
• employee_id: Employee identifier, when applicable.
• user_external_ref_id: External reference ID associated with the user/order.

User Attributes

The user_attributes object contains additional transaction and payment-related attributes. Availability and values may vary based on the payment flow and integration.

• last_4: Last four digits associated with the payment method when available.
• freedompay_merchant_reference_code: FreedomPay merchant reference code associated with the transaction.
• freedompay_invoice_number: FreedomPay invoice number associated with the transaction.
• is_card_present_transaction: Boolean indicating whether the transaction was processed as card-present.
• device_id: Identifier for the device associated with the transaction.
• internal_payment_type: Internal payment type when available; may be null.
• related_invoice_numbers: Array of invoice numbers related to the transaction.
• line_item_tax_in_cents: Object containing line-item tax information when populated.

Transaction History

The transaction_history array provides payment transaction state changes associated with the order.

• state: Transaction state, such as authorized or settled.
• time: Timestamp at which the transaction entered the specified state.

Payment Transactions

The payment_transactions array contains payment-level details associated with the order.

• authorization_amount: Amount associated with payment authorization.
• settlement_amount: Amount associated with payment settlement.
• payment_type: Payment source/type, such as cash or shift4_credit.
• card_type: Card/payment type when available.
• last_four: Last four digits of the payment method when available.
• created_at: Payment transaction creation timestamp.
• updated_at: Timestamp of the most recent payment transaction update.
• tip: Tip amount associated with the payment transaction, in cents.
• type: Payment transaction object/type, such as SalePaymentTransaction.
• status: Current payment transaction status, such as authorized.

Order State History

The state_history array records the progression of the order through its states.

• state: Order state.
• time: Timestamp at which the order entered that state.

The array may contain multiple entries as the order progresses through its lifecycle.

Line Items

The line_items array contains the individual items associated with the order.

• uuid: Unique line item ID.
• name: Item name.
• sku: Item SKU.
• price: Item price in cents.
• quantity: Quantity of the item.
• created_at: Line item creation timestamp.
• updated_at: Timestamp of the most recent line item update.
• refunded_at: Refund timestamp, when applicable.
• removed_at: Removal/void timestamp, when applicable.
• modified_line_item_uuid: Reference to the related line item when the item has been modified.
• reporting_category_uuid: Reporting category identifier, when available.
• promotion_discount: Promotion discount amount associated with the line item.
• promotions: Array containing promotions associated with the line item.
• tax_amount_in_cents: Tax associated with the line item, in cents.
• tax_inclusive: Boolean indicating whether tax is included in the item’s price.
• type: Line item type when populated; may be null.

Promotions

When promotion information is populated for a line item, the promotions array contains promotion details associated with that item.

Promotion fields may include:

• discount_amount_in_cents: Per-item promotion discount.
• uuid: Promotion ID.