​

Commerce V1 Merchant And Operator Guide

This guide is for merchant, support, security, and operations teams. It explains what Grantex Commerce V1 supports for the approved Shopify live pilot, how internal sandbox and temporary smoke evidence still fit, and which boundaries remain controlled before broader merchant or provider expansion.

​

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

​

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 readiness-review 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. C6F adds a rollout proposal and dry-run evidence workflow for operators. This workflow is available only after an operator decision of rollout_proposal_ready. The proposal records a public-safe package of sandbox profile evidence, category readiness, catalog readiness, agent-facing preview status, operator review decision, blockers, remediation, and the fixed non-enabling controls. The dry run checks the current sandbox evidence again and records either dry_run_passed or dry_run_blocked. A rollout proposal is not “go live.” A passed dry run is not approval, certification, launch, production readiness, public discovery enablement, checkout/payment enablement, live provider enablement, live Plural enablement, production config writing, or allowlist writing. Merchants still need a later separate human-approved production rollout before any customer-facing public discovery or production commerce behavior can be considered. Proposal notes and withdrawal reasons must be public-safe. Do not paste private merchant details, contracts, provider credentials, raw payloads, tokens, JWTs, DB/Redis URLs, private keys, production config values, concrete allowlist values, customer data, checkout/payment claims, live-provider claims, or launch claims into proposal evidence. C6G adds a sandbox-only AgenticOrg buyer-agent discovery preview and handoff request workflow. It packages the public-safe C6C agent-facing preview together with C6D review request evidence, C6E operator decision evidence, and C6F dry-run evidence so AgenticOrg can test a buyer-agent discovery handoff against Grantex-owned data. The handoff request is not customer-facing public discovery. It does not enable AgenticOrg public discovery, production Commerce V1, checkout/payment creation, live payments, live Plural, provider credentials, production config, or allowlists. Trusted CommerceAgent callers can read the C6G payload only after an operator records the sandbox handoff request and current blockers remain absent. Operators can withdraw the handoff request by writing new audit evidence. C6G notes and withdrawal reasons must be public-safe. Do not paste secrets, private merchant artifacts, provider credentials, raw payloads, tokens, JWTs, DB/Redis URLs, private keys, production config values, concrete allowlist values, customer data, checkout/payment claims, live-provider claims, public discovery claims, or launch claims into C6G evidence. C6R adds a sandbox connector sync dry-run foundation for merchants and operators who want to preview how an existing catalog system would map into Grantex. The first supported dry-run inputs are local manual or CSV-style catalog rows, including the C6Q DummyJSON-style fake fixture used in tests. The dry-run normalizes rows into a capped product and variant preview, records counts, blockers, warnings, and redacted audit references, and stores only tenant-scoped dry-run metadata. C6R does not connect to Shopify, WooCommerce, Magento, custom APIs, ERP, OMS, WMS, logistics, CRM/support, payment providers, Plural, Stripe, Pine, or merchant private APIs. It does not accept credentials, provider metadata, private API URLs, raw payloads, production config values, concrete allowlists, checkout URLs, payment IDs, or customer data. It does not write live catalog changes, enable outbound sync, enable public discovery, enable AgenticOrg public discovery, enable checkout/payment creation, enable live payments, or approve production launch. Merchant and operator review should look at:

• dry-run status and generated timestamp;
• row, product, variant, would-create, would-update, blocked, and warning counts;
• capped normalized preview rows;
• blocker and warning codes;
• requested/completed/blocked audit event IDs;
• fixed controls showing sandbox-only, not-live, not-approved, public discovery off, checkout/payment off, live provider off, and no provider credentials.

AgenticOrg never directly calls merchant private APIs. It continues to consume only Grantex-owned preview and buyer discovery surfaces after Grantex records the required sandbox evidence. C6Sa adds an operator review foundation for C6R dry-run evidence. A merchant or operator can request review of a tenant-scoped connector dry-run. Operators can read the redacted evidence and record one of three sandbox-only outcomes:

• accepted_for_sandbox_followup: follow-up sandbox work may continue.
• needs_changes: the merchant must fix the local snapshot or mapping before another review.
• blocked: the review is closed because the evidence is unsafe or incomplete.

The C6Sa decision is not merchant approval, production approval, connector execution approval, public discovery approval, checkout/payment approval, live provider approval, public protocol publication, or certification. It does not write catalog changes, call merchant systems, call providers, store credentials, enable outbound sync, set allowlists, or change production configuration. C6Sa review notes 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, checkout URLs, payment identifiers, customer data, live-provider claims, launch claims, or certification claims into review evidence. C6Sb adds the credential-free portal foundation for C6R dry-runs and C6Sa review evidence. Merchants and operators can use the Commerce onboarding portal to paste or select local sandbox manual/CSV catalog rows, run the tenant-scoped dry-run, review counts and capped normalized preview rows, request operator review, and record a sandbox evidence decision. The C6Sb portal panel is not production connector setup. It does not include credential entry, outbound sync controls, private API URL execution, provider setup, live merchant-system execution, public discovery controls, checkout/payment controls, live payment controls, live Plural controls, or production allowlist controls. It displays fixed safety controls such as credential_entry_enabled: false, outbound_sync_enabled: false, production_connector_setup: false, and merchant_private_api_calls: false. Operators should treat C6Sb output as internal sandbox evidence only. A passing dry-run or accepted_for_sandbox_followup review decision is not merchant approval, production approval, connector execution approval, public discovery approval, checkout/payment approval, live provider approval, public protocol publication, or certification. C6Sc hardens that portal flow for self-serve sandbox use. Merchants and operators can validate local manual/CSV rows before submission, see parsed row counts, reset the sample fixture, clear local rows, and read disabled-state reasons before requesting review or recording a decision. JSON parse errors are shown before any dry-run request is sent. C6Sc also adds a redacted evidence handoff for internal review. The handoff can be copied or downloaded locally as JSON or Markdown and includes only safe summary fields, fixed non-enabling controls, blockers, warnings, and audit references from the C6R dry-run and C6Sa review responses. It excludes raw rows, raw merchant-system payloads, credentials, tokens, provider metadata, private API URLs, checkout URLs, payment identifiers, production config values, concrete allowlists, customer data, and normalized product titles. C6Sc exports are local/internal evidence only. Do not commit timestamped or merchant-specific exports unless a later approved work item says so. A copied or downloaded handoff does not approve production launch, connector execution, public discovery, checkout/payment, live providers, public protocol publication, or certification. C6Sd adds a local evidence packet schema and operator packet review checklist to the C6Sc handoff. The packet includes a Grantex-owned schema version, checklist result, sandbox follow-up readiness summary, redaction summary, and audit references. The packet status can be ready_for_sandbox_followup, needs_operator_review, or blocked. ready_for_sandbox_followup means only that sandbox follow-up review work can continue after a passed dry-run, accepted C6Sa review, clear blockers, and fixed non-enabling controls. It is not production approval, connector execution approval, outbound sync approval, public discovery approval, checkout/payment approval, live provider approval, public protocol publication, or certification. C6Sd evidence packets remain local/internal review artifacts. They must not contain raw rows, normalized product titles, credentials, tokens, provider metadata, private API URLs, checkout URLs, payment identifiers, production config values, concrete allowlists, customer data, or secret material. C6Se adds a local operator handoff and self-serve remediation workflow to the same redacted evidence packet. A ready handoff means an operator can continue an internal sandbox follow-up conversation with the merchant. It is not production approval, connector execution approval, outbound sync approval, public discovery approval, checkout/payment approval, live provider approval, public protocol publication, or certification. If a packet is pending or blocked, the remediation workflow points merchants and operators back to the relevant C6R dry-run blockers/warnings, C6Sd packet checks, and C6Sa review decisions. needs_changes and blocked decisions keep the handoff blocked and require local snapshot remediation plus another sandbox dry-run before follow-up can continue. C6Se exports are still local/internal evidence only. They include handoff and remediation summaries, non-enabling controls, and audit references, and they exclude raw rows, raw merchant-system payloads, normalized product titles, credentials, tokens, provider metadata, private API URLs, checkout URLs, payment identifiers, production config values, concrete allowlists, customer data, and secret material. C6Sf rehearses the remediation loop locally in the portal. After a needs_changes or blocked C6Sa connector review decision, the portal can show the previous issue summary, a corrected sandbox dry-run, the refreshed packet status, and the operator follow-up status. This is only a local review-aid for sandbox evidence; it does not persist follow-up approval or enable connector execution. C6Sf followup_ready means only that a corrected dry-run has an accepted sandbox follow-up decision in the local evidence packet. It is not production approval, connector execution approval, outbound sync approval, public discovery approval, checkout/payment approval, live provider approval, public protocol publication, or certification. C6Sg persists the connector dry-run remediation loop in Grantex so the evidence does not exist only in browser state. A merchant or operator can create a tenant-scoped remediation record from a needs_changes or blocked C6Sa review, attach a corrected passed C6R dry-run, and request a follow-up C6Sa review. Duplicate remediation requests, corrected dry-run attachments, and follow-up review requests return existing evidence instead of creating duplicate rows or audit events. The persisted C6Sg record stores only redacted summary evidence: original dry-run and review IDs, original decision, remediation status, capped blocker/warning summaries, corrected dry-run ID, follow-up review ID, public-safe notes, and audit references. It does not store raw rows, raw files, raw merchant-system payloads, credentials, tokens, provider metadata, private API URLs, checkout URLs, payment identifiers, production config values, concrete allowlists, customer data, or secret material. C6Sg followup_ready means only that the corrected sandbox dry-run has a follow-up review accepted for sandbox follow-up. It is not production approval, connector execution approval, outbound sync approval, public discovery approval, checkout/payment approval, live provider approval, public protocol publication, or certification. C6Sh adds a tenant-scoped remediation queue and redacted evidence timeline for the persisted C6Sg loop. Operators can filter sandbox remediation records by merchant, status, original decision, corrected dry-run attachment, and follow-up review request. Merchants can see their own sandbox remediation status and the next safe step in the portal. The C6Sh timeline is redacted evidence visibility only. It shows remediation status, audit references, corrected dry-run and follow-up review links, and fixed non-enabling controls. It does not store or display raw connector rows, credentials, provider metadata, private API payloads, production config values, or concrete allowlists. It does not approve production launch, connector execution, outbound sync, public discovery, checkout/payment, live providers, public protocol publication, or certification. C6Sia adds backend-only operator triage controls for the same persisted remediation loop. Operators can record a tenant-scoped triage status, assignment reference, public-safe internal note, and merchant-visible follow-up guidance. Duplicate identical triage updates return the existing evidence and audit reference instead of creating duplicate rows or audit events. C6Sia triage helps the merchant understand the next sandbox correction step, for example rerunning a local manual/CSV dry-run or attaching corrected evidence. It is not production approval, connector execution approval, outbound sync approval, public discovery approval, checkout/payment approval, live provider approval, public protocol publication, or certification. The triage fields must not include raw rows, raw merchant-system payloads, credentials, tokens, provider metadata, private API URLs, checkout URLs, payment identifiers, production config values, concrete allowlists, customer data, or secret material.

​

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 Expansion Checklist

Do not expand beyond the approved Shopify live pilot if any of these are true:

• The merchant is not explicitly approved for the target environment.
• AgenticOrg commerce discovery is not gated or reviewed against the approved Grantex production discovery payload.
• Provider/live-payment/Plural production settlement signoff is missing for the claimed provider behavior.
• 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 security@grantex.dev.
• 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