Commerce V1 Merchant And Operator Guide

Merchant onboarding, catalog, policy, audit, webhook, emergency control, and production no-go guidance for Grantex Commerce V1.

Commerce V1 Merchant And Operator Guide

This guide is for merchant, support, security, and operations teams. It explains what Grantex Commerce V1 can support in internal sandbox and temporary smoke runs today, and what remains blocked before any production or live-payment use.

Operating Principle

Agents may help users find products and prepare checkout, but Grantex controls the commercial boundary:

• merchant status and catalog grounding;
• consent request and Commerce Passport issuance;
• amount caps and merchant policy;
• provider-neutral payment intent creation;
• webhook ingestion, replay controls, and reconciliation;
• audit records for review and incident response.

AgenticOrg commerce does not call Stripe, Plural, Pine, or provider credential paths directly.

Merchant Onboarding Checklist

Step	Current guidance
Tenant and merchant registration	Use synthetic fixtures for sandbox and smoke evidence. Production onboarding requires human approval.
Catalog import	Use approved catalog schemas and product/variant IDs. Keep raw supplier or provider payload dumps out of evidence.
Agent trust	Register or allow only approved agent IDs. Untrusted agents must fail safely.
Policy activation	Configure amount caps, allowed scopes, merchant status, and checkout controls.
Provider status	Mock provider only for current evidence. Live provider credentials remain blocked.
Audit review	Confirm consent, passport, cart, payment intent, and webhook metadata are observable without secret values.

Seller Self-Serve Sandbox Onboarding

C5Z adds an API-backed sandbox onboarding foundation for a tenant-owned merchant workspace. It is for preparing public-safe sandbox profile metadata only. It does not approve a merchant, enable public discovery, enable AgenticOrg public commerce discovery, enable Commerce V1 production use, create checkout or payment paths, collect provider credentials, enable live payments, or enable live Plural.

Sandbox onboarding stores only:

• display name;
• category preset;
• country and currency;
• test-safe support email or support URL;
• public discovery description draft;
• sandbox environment marker;
• agentic commerce requested flag;
• sandbox onboarding state and public-safe blocker/status summaries.

The state machine is:

draft_created -> profile_incomplete -> sandbox_ready -> submitted_for_review, with blocked, not_approved, and rollout_not_requested as fail-closed review states.

Readiness checks require a merchant profile, category preset, public-safe description, no private artifacts in public fields, no production allowlist or live-mode config values, no provider account references, and no checkout/payment enablement.

C6A extends this with a category readiness checklist and score. For electronics_appliances, required checks cover a recognized category preset, public display name, country/currency, public-safe description, and test-safe support contact. Recommended checks score sandbox product/variant presence, warranty summary, return-policy summary, India tax/GST metadata where applicable, and inventory freshness without requiring a catalog connector or exact inventory quantities in this slice. Blocked checks continue to fail closed for private artifacts, production discovery or allowlist config, live provider paths, and checkout/payment enablement.

C6B adds a computed catalog readiness preview for the same sandbox onboarding surface. It reads the merchant-owned sandbox catalog rows already stored in Grantex and reports product count, variant count, public-safe title and description coverage, category mapping, SKU coverage, price/currency coverage, image/media coverage, availability freshness, warranty summaries, return-policy summaries, tax/GST metadata where applicable, and unsafe public catalog text blockers.

Required catalog gaps block sandbox_ready and submitted_for_review because the profile is not ready for read-only discovery review. Recommended catalog gaps lower the readiness score and show remediation, but they do not require a catalog connector implementation. Operators can prepare the catalog through the existing manual product entry and CSV dry-run/bulk catalog API. Async import jobs, Shopify/WooCommerce/Magento connectors, provider credentials, checkout, payments, public discovery, live payments, and live Plural remain out of scope.

C6C adds an agent-facing preview payload to the sandbox onboarding response. The preview is tenant-scoped, read-only, and generated only from public-safe merchant profile, category readiness, and catalog readiness data already stored in Grantex. It always reports sandbox_only: true, not_live, not_approved, rollout_not_requested, public_discovery_enabled: false, checkout_payment_enabled: false, live_provider_enabled: false, and live_plural_enabled: false. It may include a capped list of public-safe sample products, allowed read-only preview labels, and blocked capability labels. It excludes private legal details, contracts, private contacts, approval evidence, pricing terms, customer data, raw payloads, credentials, tokens, provider secrets, production config values, and production allowlists.

C6D adds a read-only discovery review request workflow for sandbox merchants. The onboarding response now includes read_only_discovery_review, which shows whether the tenant-scoped sandbox merchant is eligible, requested, blocked, withdrawn, or rejected for review. A merchant or operator may request review only after the sandbox profile, category checklist, catalog checklist, and agent-facing preview all pass. The request writes audit evidence with public blocker summaries, but it is not approval and it does not publish public discovery, change production configuration, set allowlists, create checkout or payment paths, enable provider credentials, enable live payments, or enable live Plural. Blocked requests return remediation so the merchant can fix the sandbox profile or catalog before trying again.

Passing category or catalog readiness means only “sandbox profile can be reviewed”; it is not merchant approval, production readiness, public discovery approval, checkout/payment readiness, live payment readiness, or live Plural readiness.

C6E adds the operator review workflow for requests that are already pending. Operators can list pending read-only discovery review requests, inspect the readiness evidence, and record one of three audit-only outcomes:

• changes_requested: the merchant needs public-safe remediation before a later review request can proceed.
• rejected: the request is closed without approval.
• rollout_proposal_ready: the request is eligible for a later separate rollout proposal review.

rollout_proposal_ready is not approval and is not launch. It does not enable public discovery, write production config, set an allowlist, enable checkout/payment creation, enable live provider paths, or enable live Plural. Decision notes and remediation must be public-safe. Do not paste secrets, private merchant artifacts, provider credentials, raw payloads, tokens, DB/Redis URLs, private keys, production config values, concrete allowlist values, or customer data into review reasons.

Catalog And Inventory

Catalog and inventory grounding is the first safety step. Agents must not invent products, variants, prices, or availability. Operator checks should verify:

• catalog search returns merchant-owned products;
• item retrieval uses exact product and variant IDs;
• inventory checks pass the required browse passport when policy requires it;
• cart creation uses grounded variant IDs and quantities;
• evidence records synthetic IDs only when they are safe fixture identifiers.

Consent, Passport, And Amount Caps

Consent-first checkout is mandatory. A Commerce Passport is scoped runtime material and must remain out of docs, logs, PRs, chat, and evidence reports.

Operators should verify:

• consent scopes match the supported Grantex schema;
• payment amount is less than or equal to the passport cap before positive payment work proceeds;
• amount-cap breach is preserved as a fail-safe negative case;
• missing, revoked, expired, or denied passport cases stop before provider work;
• consent_exchange skip evidence uses the stable blocker code when a pre-exported checkout passport fixture is used without granted consent fixture material.

Webhook And Replay Safety

Provider webhook handling is owned by Grantex. Current evidence covers the mock provider path only. For any future live provider review:

• record secret names by name only, never values;
• avoid raw payload dumps in evidence;
• keep replay operator-only;
• verify signature handling with provider-approved material;
• confirm replay cannot change production state without explicit approval.

Emergency Disable And Re-Enable

Emergency controls must prefer fail-closed behavior:

1. Disable Commerce V1 discovery or keep it disabled.
2. Disable merchant checkout policy.
3. Remove or gate commerce agent discovery.
4. Stop temporary smoke resources and delete temporary smoke secrets.
5. Verify production grantex-auth, grantex-pg16, and grantex-redis remain unchanged after smoke runs.
6. Re-enable only through a reviewed proposal, with rollback and secret-scan evidence.

Internal Sandbox Checklist

• Use mock provider only.
• Use synthetic tenant, merchant, agent, product, and variant IDs.
• Keep usable auth material and passports under .tmp/ during approved local handoff runs.
• Record only hosts, case status, HTTP status, latency, error/blocker codes, synthetic IDs, variable names, and redacted hashes.
• Confirm cleanup of temporary Cloud Run, Cloud SQL, Redis, smoke secrets, and image tags after hosted smoke.

Production No-Go Checklist

Do not proceed to production discovery, checkout, live payments, live Plural, or external pilot claims if any of these are true:

• Grantex production Commerce V1 discovery has not been explicitly approved.
• AgenticOrg commerce discovery is not gated or reviewed against the approved Grantex production discovery payload.
• Provider/live-payment/live Plural signoff is missing.
• Legal, compliance, security, operations, and product approvals are incomplete.
• The rollback plan is missing.
• Evidence includes secrets, raw payloads, passports/JWTs, DB/Redis URLs, provider credentials, private keys, or idempotency key values.

Evidence Links

• Option A smoke evidence: operator-internal artifact, available to authorized reviewers via [e-mail].
• Production discovery readiness: operator-internal artifact, same access path.
• Repeatable workflow: docs/guides/commerce-v1-repeatable-option-a-smoke-workflow.md
• Operations guide: docs/guides/commerce-v1-operations.mdx