Athenian SwapShop for WooCommerce

Developer starting point

This baseline documents SwapShop's marketplace and settlement architecture. It does not claim that a live listing, offer, order, credit reservation, shipment, payout, or dispute mutation has been exercised.

User-Facing Workflow

1. Create a Listing

A member creates a product or service listing from the front-end listing form or WooCommerce account area. The listing can include title, description, category, tags, condition, estimated value, desired items, cash/credit preferences, shipping options, package details, pickup notes, location, service data, photos, and evidence.

2. Browse and Discover Matches

Other members browse the marketplace, filter listings, view map or explorer layouts, and review listing pages with media, summary details, highlights, trader information, trade notes, evidence, matches, and offer actions.

3. Propose a Swap

A member chooses one or more of their own open listings and proposes a swap against another member's listing. The proposal can include item selections, cash or credit terms, shipping/pickup methods, selected shipping rates, and a message.

4. Negotiate Terms

The counterparty can accept, decline, withdraw, or counter the offer. The current terms stay attached to the swap thread, and each offer revision is preserved as its own record.

5. Confirm Settlement

After an offer is accepted, each side confirms the settlement state. WooCommerce orders are created when cash, shipping, credit top-ups, or operational order records are needed. Credit holds can be confirmed through the Store Credits integration.

6. Fulfill the Trade

For physical trades, each side ships, tracks, and confirms receipt as applicable. For service trades, participants propose a schedule, approve it, start the service, request completion, and approve completion.

7. Complete, Review, and Release

When fulfillment requirements are satisfied, the swap can complete. Completion may trigger feedback prompts, credit transfer, credit rewards, payout release, analytics events, and final status updates.

8. Resolve Issues When Needed

If something goes wrong, participants can open a resolution case. The resolution workflow keeps the trade, settlement, shipping, service, feedback, and participant history in one place for admin review.

---

Administrator Workflow

Listing and Trade Management

Admins can manage listings, swaps, offers, alerts, and taxonomies from WordPress admin screens. Custom metaboxes replace generic post editing with purpose-built controls for listing details, galleries, trade state, settlement values, offer terms, resolution state, and feedback moderation.

Operations Console

The operations page is designed for daily marketplace oversight. It highlights active swaps, completed swaps, open cases, unpaid settlement items, payout issues, and shipping exceptions. Admins can open trades, trigger tracking syncs, and manage payout actions from the same console.

Feedback Moderation

The feedback page groups flagged and recent feedback into moderation tables. Staff can review ratings, breakdown scores, comments, flag reasons, moderation notes, and save updated moderation statuses.

Analytics Console

The analytics admin page embeds the Swap Shop analytics shortcode in platform scope. It is intended to show growth, liquidity, negotiation throughput, and operational friction over a configurable time window.

Trader Risk Console

The trader risk page surfaces high-risk, watchlist, and trusted trader segments. It includes trade metrics, trust/fulfillment scores, open cases, flagged feedback, risk flags, and shortcuts to edit users or review their listings.

Email Event Management

The plugin includes a Swap Emails admin area for reviewing and triggering configured email events. This is useful for testing and managing communication flows across the swap lifecycle.

---

Technical Architecture

Main Bootstrap

The main plugin file defines constants and boots Athenian\SwapShop\Plugin on plugins_loaded priority 20.

define('ATH_SWAP_FILE', __FILE__);
define('ATH_SWAP_DIR', plugin_dir_path(__FILE__));
define('ATH_SWAP_URL', plugin_dir_url(__FILE__));
define('ATH_SWAP_VERSION', '0.3.52');

The plugin registers activation and deactivation hooks to set defaults, register post types and meta, add rewrite endpoints, schedule cron jobs, and flush rewrite rules.

Service-Oriented Boot Process

The Plugin class loads and boots services for settings, post types, meta registration, assets, admin UI, email events, notifications, shipping estimates, labels, tracking, reminders, confirm-swap endpoint, WooCommerce account endpoint, settlement manager, alerts, and integrations.

Core services include:

• Settings
• PostTypes
• Meta
• Assets
• Admin
• Email_Events
• Notifications
• Shipping_Estimates
• Labels
• Tracking
• Reminders
• Confirm_Swap_Endpoint
• Woo\Account
• Woo\Settlement_Manager
• Domain\Alerts
• Integrations\ASU
• Integrations\ADI
• Integrations\OwlPay
• Integrations\StoreCredits

Shortcodes and REST routes are registered after services boot.

---

Custom Post Types and Taxonomies

Custom Post Types

| Post Type | Purpose | Visibility | |---|---|---| | ath_swap_listing | Public swap listings, wanted posts, products, and services | Public, REST-enabled | | ath_swap_trade | Private swap negotiation and fulfillment record | Admin UI, REST-enabled | | ath_swap_offer | Private offer/counteroffer records attached to swaps | Admin UI, REST-enabled | | ath_swap_alert | Saved alerts and wanted-post match rules | Admin UI, REST-enabled |

Taxonomies

| Taxonomy | Applies To | Purpose | |---|---|---| | ath_swap_listing_cat | Listings and swaps | Hierarchical swap categories | | ath_swap_listing_tag | Listings | Free-form swap tags | | ath_swap_listing_condition | Listings | Listing condition labels | | ath_swap_exchange_type | Swaps | Exchange type classification |

On first registration, the plugin can seed default listing conditions such as New, Like New, Excellent, Good, Fair, and Parts or Repair.

---

Data Model Summary

Listing Metadata

Listing records store owner identity, listing state, trade preferences, condition, value, credit market settings, fulfillment configuration, shipping package fields, pickup availability, geolocation, service data, wants/desired terms, gallery media, and active trade count.

Important listing fields include:

• owner_user_id
• owner_person_id
• owner_vendor_id
• listing_status
• listing_kind
• listing_asset_type
• condition_note
• desired_items
• estimated_value
• cash_preference
• accepts_credit_bids
• accepts_credit_buy_now
• credit_bid_floor
• credit_bid_increment
• credit_buy_now_price
• allow_shipping
• allow_local_pickup
• package_weight
• package_length
• package_width
• package_height
• location_label
• geo_lat
• geo_lng
• service_offer_id
• service_duration_minutes
• service_radius_miles
• wants_json
• gallery_image_ids
• active_swap_count

Swap Metadata

Swap records store participant identity, listing selections, cash and credit terms, shipping estimates, payer maps, offer state, swap lifecycle state, WooCommerce order IDs, settlement state, payout state, label and tracking data, service schedule data, feedback, resolution data, reminders, and audit logs.

Important swap fields include:

• initiator_listing_id
• counterparty_listing_id
• initiator_user_id
• counterparty_user_id
• initiator_cash
• counterparty_cash
• initiator_settlement_type
• counterparty_settlement_type
• initiator_credit_units
• counterparty_credit_units
• shipping_estimate_json
• shipping_payers_json
• fulfillment_methods_json
• current_offer_id
• accepted_offer_id
• offer_count
• swap_status
• swap_fulfillment_mode
• initiator_order_id
• counterparty_order_id
• settlement_status
• payments_cleared_at
• payout_status
• initiator_label_path
• counterparty_label_path
• initiator_tracking
• counterparty_tracking
• initiator_tracking_status
• counterparty_tracking_status
• service_status
• service_scheduled_start
• service_scheduled_end
• service_schedule_location
• completed_at
• cancelled_at
• resolution_status
• resolution_updates
• audit_log

Offer Metadata

Offer records store the proposed terms for a specific negotiation step.

Important offer fields include:

• swap_id
• parent_offer_id
• sender_user_id
• recipient_user_id
• sender_role
• initiator_listing_id
• counterparty_listing_id
• initiator_cash
• counterparty_cash
• initiator_settlement_type
• counterparty_settlement_type
• initiator_credit_units
• counterparty_credit_units
• shipping_estimate_json
• shipping_payers_json
• fulfillment_methods_json
• proposal_type
• message
• offer_status
• responded_at

Alert Metadata

Alert records store saved matching rules and notification state.

Important alert fields include:

• user_id
• keywords
• category_id
• subcategory_id
• listing_kind
• source_listing_id
• is_active
• match_count
• matched_listing_ids
• last_sent_at

---

REST API Surface

The plugin registers routes under the ath-swap/v1 namespace.

| Route | Methods | Purpose | |---|---:|---| | /ping | GET | Basic availability check | | /listings | GET | Query listings, including current user's listings | | /listings | POST | Create a listing | | /listings/{id} | GET | Read editable listing details | | /listings/{id} | POST | Update a listing | | /browse/listings | GET | Public marketplace browse query | | /browse/value-range | GET | Value range for filters | | /listings/{id}/swap-options | GET | Eligible proposal options for a target listing | | /listings/{id}/message-owner | POST | Send contextual owner message when ASU is available | | /categories | GET | Listing category lookup | | /tags | GET | Listing tag lookup | | /conditions | GET | Condition lookup | | /service-offers | GET | Service offer lookup | | /listings/ai-suggest | POST | AI listing enrichment suggestions | | /dashboard | GET | Member dashboard payload | | /dashboard/payouts | GET | Payout and credit dashboard payload | | /dashboard/payouts/cashout | POST | Request credit cashout | | /dashboard/payouts/request | POST | Request OwlPay payout | | /analytics | GET | Analytics dashboard data | | /suggestions | GET | Suggested matches | | /alerts | GET | List current user's alerts | | /alerts | POST | Create an alert | | /alerts/{id} | DELETE | Delete an alert | | /swaps | POST | Create a proposal | | /shipping/estimate | POST | Estimate shipping for selected trade terms | | /swaps/{id}/accept | POST | Accept current offer | | /swaps/{id}/confirmation | POST | Confirm accepted swap terms | | /swaps/{id}/checkout/confirm | POST | Confirm checkout/credit hold state | | /swaps/{id}/offers | POST | Create counteroffer | | /swaps/{id}/message | POST | Send trade-context message | | /swaps/{id}/decline | POST | Decline current offer | | /swaps/{id}/withdraw | POST | Withdraw current offer | | /swaps/{id}/cancel | POST | Cancel open negotiation | | /swaps/{id}/feedback | POST | Submit post-completion feedback | | /swaps/{id}/resolution | POST | Open a resolution case | | /swaps/{id}/resolution/reply | POST | Add resolution note | | /swaps/{id}/service/schedule | POST | Propose service schedule | | /swaps/{id}/service/approve-schedule | POST | Approve service schedule | | /swaps/{id}/service/start | POST | Start service work | | /swaps/{id}/service/complete | POST | Request/mark service completion | | /swaps/{id}/service/approve-completion | POST | Approve service completion | | /swaps/{id}/ship | POST | Mark a side shipped | | /swaps/{id}/receive | POST | Mark incoming shipment received |

Most write routes require a logged-in user and rely on capability checks or swap/listing ownership validation.

---

Shortcodes

| Shortcode | Purpose | |---|---| | [ath_swap_shop] | Marketplace wrapper/entry point | | [ath_swap_listing_form] | Front-end listing composer | | [ath_swap_browse_explorer] | Combined marketplace browser | | [ath_swap_browse_search] | Browse search component | | [ath_swap_browse_filters] | Browse filter component | | [ath_swap_browse_results] | Browse result component | | [ath_swap_browse_map] | Map component | | [ath_swap_dashboard] | Member swap dashboard | | [ath_swap_dashboard_widget] | Compact dashboard widget | | [ath_swap_alert_form] | Saved alert form | | [ath_swap_confirm] | Accepted swap confirmation UI | | [ath_swap_checkout] | Swap checkout/settlement review UI | | [ath_swap_analytics] | Analytics dashboard | | [ath_swap_trader_profile] | Public/member trader profile | | [ath_swap_resolution_center] | Resolution center UI | | [ath_swap_listing_single] | Full single-listing display | | [ath_swap_listing_single_hero] | Single-listing hero fragment | | [ath_swap_listing_single_media] | Single-listing media fragment | | [ath_swap_listing_single_gallery] | Single-listing gallery fragment | | [ath_swap_listing_single_summary] | Single-listing summary fragment | | [ath_swap_listing_single_highlights] | Single-listing highlights fragment | | [ath_swap_listing_single_description] | Single-listing description fragment | | [ath_swap_listing_single_trade_notes] | Single-listing trade notes fragment | | [ath_swap_listing_single_evidence] | Single-listing evidence fragment | | [ath_swap_listing_single_matches] | Single-listing match suggestions fragment | | [ath_swap_listing_single_trader] | Single-listing trader fragment | | [ath_swap_listing_single_offer] | Single-listing offer/proposal fragment |

The fragment shortcodes make it easier to build custom Bricks/WordPress layouts while still using the plugin's underlying listing data and interaction model.

---

Ecosystem Integrations

WooCommerce

WooCommerce is the required settlement backbone. Swap Shop uses WooCommerce customer identity, orders, account endpoints, order status hooks, shipping item metadata, currency helpers, and product records for support products.

Athenian Store Credits

The Store Credits integration supports credit normalization, credit balance checks, credit reservations, checkout holds, credit transfers, cancellation releases, shipping credit handling, completion rewards, and credit cashout payloads.

OwlPay

The OwlPay integration supports held payouts, payout release, payout blocking when resolutions open, admin release behavior, user payout snapshots, and payout requests.

Athenian Social Users Core

The ASU integration connects Swap Shop to richer identity, messaging, alerts, person records, score events, trader snapshots, person-editor panels, contextual messaging permissions, and trust score enrichment.

Athenian Data Intelligence

The ADI integration emits lifecycle events such as listing created, offer created, offer accepted, payments cleared, labels ready, delivered tracking, tracking exceptions, resolutions, feedback, payout release/block, and completion.

Shipping Integrations

The shipping layer can work with Athenian carrier methods/classes for UPS, FedEx, USPS, and internal logistics when available. It also exposes filters for custom carrier rates, tracking lookup, registered carrier labels, and cache context.

Athenian Platform Core AI

When Athenian Platform Core AI is available, the listing assistant can call a chat.complete capability and request structured JSON listing suggestions.

---

Important Hooks and Extension Points

Actions

| Hook | Purpose | |---|---| | ath_swap_booted | Fired after plugin services and routes are registered | | ath_swap_listing_created | Fired when a listing is created | | ath_swap_offer_created | Fired when an offer is created | | ath_swap_offer_accepted | Fired when an offer is accepted | | ath_swap_payments_cleared | Fired when settlement requirements clear | | ath_swap_labels_ready | Fired when labels are generated/ready | | ath_swap_side_marked_shipped | Fired when a side marks shipped | | ath_swap_tracking_delivered | Fired when tracking reports delivered | | ath_swap_tracking_exception | Fired when tracking reports exception | | ath_swap_tracking_synced | Fired after tracking sync | | ath_swap_resolution_opened | Fired when a resolution opens | | ath_swap_resolution_status_updated | Fired when resolution status changes | | ath_swap_feedback_submitted | Fired when feedback is submitted | | ath_swap_feedback_moderated | Fired when feedback moderation changes | | ath_swap_payout_released | Fired when payout release occurs | | ath_swap_payout_blocked | Fired when payout is blocked | | ath_swap_completed | Fired when a swap completes | | ath_swap_cancelled | Fired when a swap is cancelled |

Filters

| Filter | Purpose | |---|---| | ath_swap_shipping_estimate_cache_context | Customize shipping estimate cache context | | ath_swap_shipping_estimate_cache_ttl | Customize shipping estimate cache duration | | ath_swap_shipping_rates | Inject or modify swap shipping rates | | ath_swap_generate_label | Generate label artifacts for a swap side | | ath_sm_registered_carriers | Register carrier label callbacks | | ath_swap_tracking_lookup | Provide live carrier tracking lookup results | | asu_person_meta_schema | Extend ASU person schema with swap fields | | asu_message_send_allowed | Allow contextual swap messages through ASU | | asu_person_score_calculated | Enrich canonical ASU person scores with swap behavior |

---

Security and Permissions Notes

• The plugin uses WordPress login checks and ownership validation for listing edits and swap actions.
• Write routes generally require current_user_can('read') and additional contextual validation.
• Admin operations pages require manage_woocommerce or manage_options.
• Admin AJAX lookup uses a nonce.
• Settings are sanitized through the WordPress Settings API.
• Registered post meta uses sanitization callbacks based on field type.
• Public browsing routes intentionally expose open listings, while private negotiation, dashboard, settlement, and management routes require authentication.
• The plugin prevents users from targeting their own listings for swap proposals and blocks conflicting proposals when a listing is unavailable, reserved, closed, wanted-only, or already involved in active trade activity.

---