Public integration overview
PUPMKT is a connector-ready marketplace frontend. It keeps the browser experience stable while approved partner services remain authoritative for identity, inventory, commerce, fulfillment, and other live decisions.
Full API contract 2.1.0, all 114 documented operations, schema catalogue, browser-command mapping, mock environment, integration examples and contract-test package are available to qualified partners upon request.
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.1 defines 95 provider-neutral paths, 114 documented operations, and 37 named browser-command mappings. The boundary follows real frontend 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.
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 authoritative partner 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.1.0 is the current compatibility boundary. Its category-governance operations and partner-retail Nearby projection are additive; breaking field, operation, or meaning changes still require a new major version and migration evidence.
Connected-pilot dependencies
PUPMKT supplies the frontend boundary and integration contract. A connected pilot requires approved owners and test services for the capabilities placed in scope.
Narrow seven-day pilot
This is an integration exercise for a controlled test cohort. 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 37 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.