Athenian Tickets & Admission

Developer starting point

This baseline is generated from the reviewed local technical reference and source folder. Deployed-version parity and external-provider effects remain separate verification steps.

5. Customer-Facing Workflow

Purchase Flow

1. A merchant marks a WooCommerce product as a Ticket / Admission Product.
2. The product is enriched with optional event metadata such as event name, schedule, venue, ticket label, terms, and customer email notes.
3. A customer purchases the product like any other WooCommerce item.
4. When the order reaches one of the configured generation statuses, the plugin creates one ticket record per purchased quantity.
5. The customer receives ticket details in WooCommerce email content and, when enabled, attached ticket PDFs.
6. The customer can later access tickets through the WooCommerce My Account ticket wallet or secure download links.

Customer Ticket Wallet

The plugin registers a WooCommerce My Account endpoint:

/ath-tickets/

It adds a Tickets menu item after the standard WooCommerce Orders menu item. The wallet searches tickets by the logged-in user’s account email and displays ticket cards with:

• Ticket status.
• Event name.
• Event schedule.
• Venue.
• Attendee or customer name.
• Ticket code.
• Barcode/QR display grid.
• PDF download button.

Secure Download Flow

Ticket PDF download links are generated through frontend query arguments:

?ath_ticket_download=1&ticket_id={ticket_id}&key={access_key}

Downloads are allowed for:

• WooCommerce managers or users who can edit shop orders.
• Logged-in customers whose account email matches the ticket customer email.
• Guests with a valid ticket-specific access key, when guest downloads are enabled.

---

6. Staff, Kiosk, and POS Workflows

Staff Check-In Console

Shortcode:

[ath_ticket_checkin]

This renders a staff-facing lookup and redemption console for users with manage_woocommerce or edit_shop_orders. It includes same-day issued and redeemed KPI tiles, manual ticket code entry, lookup, and redeem actions.

Kiosk Redemption Station

Shortcode:

[ath_ticket_kiosk]

This renders a scanner-first entry station for logged-in staff. It supports:

• Manual ticket code entry.
• Hardware scanner input.
• Optional auto-redeem behavior.
• Camera scanning when the browser supports BarcodeDetector and getUserMedia.
• QR-focused or hybrid scanner modes.

The kiosk can operate in auto-redeem mode when enabled in settings, allowing a scan or Enter key action to redeem instead of only lookup.

POS Ticketing Hub

Shortcode:

[ath_ticket_pos]

This shortcode creates a POS ticketing hub. It can link to a configured POS page, display ticket operations guidance, open ticket reporting, and embed the Athenian POS shortcode when [athenian_pos] is active and POS embedding is enabled.

Direct Download Shortcode

[ath_ticket_download code="XXXXX-XXXXX-XXXXX-XXXXX"]

This shortcode resolves a ticket by code and redirects to the secure PDF download URL.

---

7. Ticket Product Configuration

The plugin adds ticket-specific fields to the WooCommerce product editor general product data panel.

| Product Meta Key | Admin Label | Purpose | |---|---|---| | _ath_ticket_enabled | Ticket / Admission Product | Enables ticket generation and redemption behavior for the product. | | _ath_ticket_event_name | Event name | Optional event name shown on tickets and reports. | | _ath_ticket_ticket_label | Ticket label | Optional ticket type badge, such as General Admission or VIP. | | _ath_ticket_event_start | Event start | Structured start date/time used for tickets, kiosk screens, and reports. | | _ath_ticket_event_end | Event end | Optional structured end date/time. | | _ath_ticket_event_date | Event schedule summary | Plain-language schedule fallback such as “Doors at 6 PM, show at 7 PM.” | | _ath_ticket_venue | Venue | Venue or location line. | | _ath_ticket_terms | Ticket terms | Short terms line such as “Non-refundable.” | | _ath_ticket_email_note | Email note | Optional note included in ticket emails and PDF body. |

When a ticket is generated, these product-level values are copied onto the individual ticket record so the ticket retains the event context even if the product is edited later.

---

8. Ticket Record Model

The plugin registers a private admin-visible custom post type:

ath_ticket

Tickets are shown under the WooCommerce admin menu and support title-only editing. The ticket title is the generated ticket code.

Ticket Statuses

| Status | Label | Meaning | |---|---|---| | ath_unredeemed | Unredeemed | Ticket has been issued and is valid for entry. | | ath_redeemed | Redeemed | Ticket has already been used. | | ath_voided | Voided | Ticket has been cancelled or invalidated. |

Core Ticket Metadata

| Ticket Meta Key | Purpose | |---|---| | _ath_ticket_code | Human-readable unique ticket code. | | _ath_ticket_access_key | Secure per-ticket download key. | | _ath_ticket_order_id | Origin WooCommerce order ID. | | _ath_ticket_order_item_id | Origin WooCommerce line item ID. | | _ath_ticket_product_id | Origin product ID. | | _ath_ticket_product_name | Captured line item/product name. | | _ath_ticket_price | Unit ticket price derived from the order line total divided by quantity. | | _ath_ticket_customer_email | Billing/customer email at time of issue. | | _ath_ticket_customer_name | Billing/customer name at time of issue. | | _ath_ticket_attendee_name | Optional attendee name captured from add-ons or line item metadata. | | _ath_ticket_channel | Order channel, typically web or pos. | | _ath_ticket_issued_at | Issuance timestamp. | | _ath_ticket_redeemed_at | Redemption timestamp when redeemed. | | _ath_ticket_redeemed_by | User ID of the staff user who redeemed the ticket. | | _ath_ticket_redemption_channel | Redemption channel such as checkin, kiosk, or api. | | _ath_ticket_redemption_note | Optional redemption note. | | _ath_ticket_voided_at | Void timestamp when voided. | | _ath_ticket_voided_note | Optional void note. | | _ath_ticket_voided_channel | Void source/channel. | | _ath_ticket_ean13 | Generated EAN-13 numeric barcode value. | | _ath_ticket_upca | Generated UPC-A numeric barcode value. | | _ath_ticket_pdf417_text | Text payload for PDF417-style barcode output. | | _ath_ticket_order_total | Captured order total when the ticket is created. |

Ticket Code Format

Ticket codes are generated from a Crockford-style Base32 alphabet that avoids visually confusing characters. The generated format is:

XXXXX-XXXXX-XXXXX-XXXXX

The sanitizer allows uppercase letters, numbers, and hyphens. Lookup also supports the generated EAN-13 and UPC-A numeric values.

---

11. Operational Settings

Settings are stored in the WordPress option:

ath_tickets_settings

Default Settings

| Setting | Default | Purpose | |---|---:|---| | generate_statuses | processing, completed | Order statuses that trigger ticket generation. | | email_pdf_attachments | yes | Attach generated ticket PDFs to customer processing/completed emails. | | allow_guest_downloads | yes | Allow access-key-based guest downloads. | | kiosk_auto_redeem | no | Let kiosk scans or Enter actions redeem automatically. | | pos_embed_enabled | yes | Allow [ath_ticket_pos] to embed [athenian_pos] when available. | | pos_page_url | empty | Optional URL for opening a POS page. | | report_window_days | 30 | Default dashboard report window. | | scanner_mode | hybrid | Scanner mode: hybrid, manual, or qr. | | digital_qr_enabled | yes | Flag exposed to frontend scripts for digital QR behavior. | | qr_payload_mode | code | QR payload can be ticket code or scan URL. | | api_enabled | yes | Enables token-based REST access for non-privileged external callers. | | api_access_token | generated | Token for REST API access. | | webhook_enabled | no | Enables outgoing webhook dispatch. | | webhook_secret | generated | HMAC signing secret for webhooks. | | webhook_urls | empty | Destination URLs for webhook delivery. | | webhook_events | created, redeemed, voided, generated | Enabled webhook event names. | | webhook_timeout | 10 | Webhook request timeout in seconds. |

The activation flow creates defaults, generates missing API and webhook secrets, registers the ticket CPT, and flushes rewrite rules.

---

13. REST API

The plugin registers a REST namespace:

ath-tickets/v1

Authentication

REST routes are available to users with WooCommerce management capabilities. External callers can authenticate with the generated API token when the API is enabled.

Supported token formats:

Authorization: Bearer {API_TOKEN}

or:

X-Ath-Tickets-Token: {API_TOKEN}

Endpoints

| Method | Endpoint | Purpose | |---|---|---| | GET | /wp-json/ath-tickets/v1/health | Health and configuration check. | | GET | /wp-json/ath-tickets/v1/tickets | List tickets by page, status, channel, order, product, email, or code. | | POST | /wp-json/ath-tickets/v1/tickets/lookup | Lookup a ticket from a posted code. | | GET | /wp-json/ath-tickets/v1/tickets/{id} | Fetch a single ticket payload by ticket ID. | | POST | /wp-json/ath-tickets/v1/tickets/{id}/redeem | Redeem a ticket by ID. | | POST | /wp-json/ath-tickets/v1/tickets/code/{code}/redeem | Redeem directly from a scanned ticket code. | | POST | /wp-json/ath-tickets/v1/tickets/{id}/void | Void a ticket. | | GET | /wp-json/ath-tickets/v1/orders/{id}/tickets | Retrieve all tickets attached to an order. | | POST | /wp-json/ath-tickets/v1/orders/{id}/generate | Force ticket generation for an order. | | GET | /wp-json/ath-tickets/v1/reports/summary | Return summary metrics and event breakdown. |

Ticket List Filters

The ticket list endpoint supports these query-style filters:

• code
• page
• per_page
• order_id
• product_id
• customer_email
• status
• channel

Ticket responses include pagination metadata and set X-WP-Total / X-WP-TotalPages headers.

---

14. AJAX Interface

Frontend staff tools use WordPress AJAX actions:

| AJAX Action | Purpose | Access | |---|---|---| | ath_tickets_lookup | Lookup a ticket by code. | Logged-in staff with manage_woocommerce or edit_shop_orders. | | ath_tickets_redeem | Redeem a ticket by code. | Logged-in staff with manage_woocommerce or edit_shop_orders. | | ath_tickets_summary | Fetch same-day summary metrics. | Logged-in staff with manage_woocommerce or edit_shop_orders. |

All AJAX requests require the ath_tickets_frontend nonce. The inspected implementation does not expose nopriv AJAX actions, which keeps lookup and redemption actions restricted to authenticated staff workflows.

---

15. Webhooks

The webhook dispatcher listens to internal ticket lifecycle actions and sends signed JSON payloads to configured URLs.

Supported Events

| Event | Trigger | |---|---| | ticket.created | A ticket record is created. | | ticket.redeemed | A ticket is redeemed. | | ticket.voided | A ticket is voided. | | order.tickets_generated | One or more tickets are generated for an order. |

Webhook Payload Envelope

Webhook bodies include:

• delivery_id
• event
• sent_at_gmt
• site.name
• site.url
• data

Webhook Headers

The dispatcher sends:

Content-Type: application/json
User-Agent: AthenianTicketsWebhook/{version}
X-Ath-Tickets-Event: {event}
X-Ath-Tickets-Delivery: {delivery_id}
X-Ath-Tickets-Time: {timestamp}
X-Ath-Tickets-Signature: {signature}

The signature is calculated as an HMAC-SHA256 hash over:

{timestamp}.{rawBody}

using the configured webhook signing secret.

Delivery Result Hook

After a webhook attempt completes, the plugin fires:

do_action('ath_tickets/webhook_delivery_result', $event, $url, $data, $response, $delivery_id);

This provides a useful integration point for logging, retry queues, observability, or admin delivery history in a future release.

---

16. Athenian POS Integration

The plugin includes an integration class for the Athenian POS workflow.

POS Hook

add_action('athpos/order_created', [POS::class, 'capture_pos_order'], 20, 2);

When a POS order is created, the plugin:

1. Tags the order with _ath_ticket_channel = pos.
2. Stores _ath_ticket_pos_register from the POS payload when available.
3. Checks whether the order includes ticket-enabled products.
4. Runs ticket generation for POS-origin orders when applicable.

Reporting Impact

The ticket summary counts tickets whose channel is pos, allowing operators to compare web-issued and POS-issued ticket volume within the WooCommerce Ticketing dashboard.

---

17. WooCommerce Email Integration

The plugin integrates with WooCommerce customer emails through:

woocommerce_email_attachments
woocommerce_email_after_order_table

Email Attachments

When enabled, ticket PDFs are attached to:

• customer_processing_order
• customer_completed_order

Before attaching PDFs, the plugin calls ticket generation for the order to ensure missing tickets are created.

Email Body Details

The customer email body includes a Your Tickets section with each ticket’s event name, ticket code, download link, and optional email note.

---