Public integration overview
PUPMKT brings the customer, seller, support, store, and employee experiences together in one marketplace product. Its server and database foundations are being completed so approved identity, inventory, payment, notification, fulfillment, and workforce systems can connect without rebuilding those experiences. External providers and operating controls remain authoritative for live decisions.
The complete API contract 2.28.0, all 219 documented operations, schema catalogue, browser-command mapping, mock environment, integration examples and contract-test package are available to qualified partners upon request. It includes customer-owned tracked support, participant-authorized scan-gated message attachments, separate internal and customer-visible support channels, task-bound item observation, category-specialist authentication, custody, managed packing, pickup challenge delivery, pickup release, dual-employee store transfers, independent transfer-exception review, exact employee return receipt, inspection and refund-review tasks, and governed post-auction aftercare. The browser cannot choose an assigned item, transition, evidence set, package profile, recipient channel, transfer location, recovery plan, refund amount, provider, customer, release item set, auction candidate, deadline, or account-health outcome. Provider-dependent capabilities remain disabled until their migrations, providers, identity, authorization, monitoring, and operating evidence are approved.
Partner builds also publish a machine-readable readiness record. Every disabled production capability names its connector, policy, and configuration prerequisites and remains non-retryable until those reviewed conditions are met. The record contains no credentials, private service locations, or database identifiers.
System context
The public site exposes a stable customer interface and a same-origin gateway. Credentials, business rules, and private service locations remain on trusted server infrastructure.
Search, listings, accounts, cart, checkout handoff, orders, selling, stores, and digital eligibility.
Accepts browser requests, carries the approved session, and prevents partner credentials from entering frontend code.
Maps the provider-neutral PUPMKT contract to approved services without exposing nonpublic service locations.
Own identity, inventory, pricing, payments, orders, fulfillment, support, and approved transfer decisions.
Request flow
Reads and commands follow the same controlled path, so loading, authorization, conflicts, and outages can be represented honestly.
A customer or authorized workforce user starts a visible action.
The browser sends the minimum validated projection to the PUPMKT gateway.
The server establishes the actor and enforces role, scope, and resource ownership.
The responsible partner system reads or changes the record and returns its current version.
The gateway returns a contract-valid response or a stable, user-safe error with a correlation reference.
No synthetic success in connected mode. If a remote catalog, cart, checkout, order, or identity service fails, PUPMKT shows an unavailable or retry state. It never silently substitutes synthetic sellable inventory or invents an authoritative transaction.
Supported business domains
Contract 2.28.0 defines 192 provider-neutral paths, 219 documented operations, and 54 named browser-command mappings. The boundary follows real product workflows instead of an inflated speculative endpoint count.
Versioned categories, browse and search results, listing detail, seller summaries, availability, pricing, condition, and approved media. Qualified employee roles can govern category records without making the browser authoritative.
Versioned cart projections, hosted checkout handoff, authoritative checkout return status, orders, fulfillment, and return context.
Seller profile projections, listing drafts, owner-scoped inventory, offers, auctions, bids, and marketplace messages.
Item evidence, validation context, store-assisted fulfillment, issue handling, and Nearby results that can combine clearly labeled marketplace listings with eligible partner-retail inventory.
Customer and workforce session projections, roles, scopes, saved items, account preferences, and deny-by-default ownership checks.
Hosted onboarding projections and digital eligibility or transfer handoffs only when the responsible program explicitly permits them.
Agent-assisted shopping
The public site does not yet connect a shopping assistant. PUPMKT's first agent-commerce foundation starts with governed, read-only discovery planning against the same listings, prices, availability, and policies customers see.
A future authorized assistant can search and compare current listings without receiving private account details or seller-only information.
A customer can limit categories, sellers or merchants, delivery choices, maximum spend, and how long permission lasts.
When approval is required, the customer sees the selected item, current total, source, and next action before anything consequential can continue.
Decisions can retain a reviewable record of the assistant, permission, quote, result, and time without copying private shopping content into public logs.
Agent purchasing is not active in this release. No shopping assistant can reserve an item, place a bid, accept an offer, start payment, or complete an order until the related identity, permission, approval, audit, payment, and recovery controls pass their own release gates.
Identity and authorization
PUPMKT consumes a minimal session projection. Authentication is supplied through an approved identity handoff; every protected decision is authorized again on the server.
Supports account, buyer, and seller experiences. The session identifies the actor, while the server checks ownership of profiles, carts, listings, messages, and orders before returning or changing data.
Uses a separate enterprise identity boundary and narrowly scoped session projection. Directory credentials never enter PUPMKT forms, and customer sessions do not become workforce sessions.
Operating modes
The mode changes the source of truth, not the product's navigation or visual hierarchy.
Live capabilities are closed. The interface can demonstrate category governance, Nearby retail presentation, and the complete customer surface, but it does not claim that accounts, store inventory, payments, orders, payouts, store decisions, or digital transfers are operating.
Only accepted capabilities are enabled. Every public category, listing, store-stock fact, price, and successful command comes from an approved PUPMKT or external service through the same-origin gateway.
Representative projections
These sanitized summaries show the information each screen needs. They are not the full schema catalogue or endpoint reference.
{ authenticated, actorType, roles, scopes, expiresAt }Enough to render the current actor and request permitted actions without exposing provider tokens.
{ items, nextCursor, appliedFilters }A stable result window with public availability and discovery context.
{ id, title, condition, price, seller, fulfillment, version }The current item, seller, evidence, price, delivery choices, and concurrency version.
{ id, items, authoritativeTotals, version }Server-priced entries, eligible fulfillment choices, totals, and a version for safe updates.
{ sessionReference, status, expiresAt }An opaque hosted-checkout handoff. A browser redirect alone never proves payment or order creation.
{ id, status, items, total, fulfillment, timeline, version }An ownership-filtered view of the authoritative order and customer-safe progress.
Sanitized examples
These abbreviated examples use synthetic identifiers and nonfunctional placeholders. Qualified documentation supplies complete schemas, errors, examples, and executable tests.
GET /api/v1/listings?category=retro-games&limit=2
Accept: application/json
200 OK
{
"items": [
{
"id": "listing_demo_001",
"title": "Synthetic game listing",
"condition": "excellent",
"price": { "amountCents": 4299, "currency": "USD" }
}
],
"nextCursor": null
}POST /api/v1/checkout-sessions
Content-Type: application/json
Idempotency-Key: [unique intent key]
{
"cartId": "cart_demo_001",
"expectedCartVersion": 4,
"fulfillmentMethod": "shipment"
}
201 Created
{
"checkoutSessionId": "checkout_demo_001",
"status": "pending",
"checkoutDestination": "[approved hosted checkout URL]"
}Reliability model
The public overview describes the guarantees without publishing implementation-specific security or operational details.
Commands that could duplicate state use a caller-stable intent key. Exact replays return the established result; mismatched reuse is rejected instead of creating a second action.
Partner event delivery is authenticated, replay-aware, and idempotently processed. Duplicate and out-of-order delivery are expected; reconciliation remains available when delivery is delayed.
Failures use stable machine codes, a user-safe summary, a correlation reference, and clear retry guidance. Private dependency details and stack traces are not returned to the browser.
Contract 2.28.0 is the current unissued pre-pilot integration boundary. It adds protected message-attachment upload, scan-state and participant-view operations plus task-bound employee return receipt, inspection and refund review. A refund approval only queues execution and explicitly reports that no funds have moved. It retains customer-owned support, governed store validation, pickup challenge/release, cross-location transfer duties, independent transfer-exception review, owner-bound returns, seller-scoped fulfillment, customer agent controls, accepted-offer checkout, private auction terms, winner-bound auction checkout, and independently approved partial-reserve exceptions backed by resolved reconciliation evidence. Provider-dependent capabilities remain disabled until the required migrations, providers, identity, authorization, monitoring, workers, and operating evidence are approved. Earlier adapters must regenerate their types and rerun schema and negative authorization tests before activation.
Connected-pilot dependencies
PUPMKT supplies the marketplace application, core data model, service layer, provider adapters, and integration contract. A connected pilot still requires approved owners and test services for every capability placed in scope.
Focused connection pilot
This is an integration exercise for a controlled test cohort. Its timing depends on working partner sandboxes, representative data, responsible owners, and approved decisions. It is not a production launch, public money-movement approval, store rollout, or claim that every partner system is already operating.
Name owners, test data, one region, one catalog slice, the authoritative systems, acceptance evidence, and rollback authority.
Map category, listing, and any in-scope partner-retail projections, then establish a customer test session with ownership and denial checks.
Wire the server cart, hosted test checkout, authoritative return status, and order projection with safe retries.
Exercise failure, accessibility, monitoring, disablement, rollback, and reconciliation before recording a pilot decision.
Production remains a separate decision. Legal, security, privacy, payments, operations, support, reliability, accessibility, and business owners must accept their launch responsibilities before live use.
Qualified-partner access
The qualified package is version-specific and can include a searchable rendered reference, full schemas, all 54 browser-command mappings, workflow guides, sanitized working examples, a deterministic mock environment, contract tests, a package manifest, and checksums. Access is individually approved, time-bounded, logged, and revocable.
The API contract appears structurally suitable for conventional partner integration, but independent no-AI usability verification remains pending.