​

Commerce V1 Developer Guide

This guide explains how developers should reason about the Grantex Commerce V1 contract. Production Commerce V1 is deployed for the approved Shopify pilot merchant mch_shopify_mgx0n6_22. This guide does not publish secret material and does not claim production Plural settlement while the available Plural credentials authenticate against UAT-compatible rails.

​

API And MCP Surface

Developers should use the OpenAPI contract in docs/api/grantex-commerce-v1.openapi.yaml plus the MCP tool surface exposed by the Commerce service. The current AgenticOrg integration uses these Grantex-only aliases:

​

Schema.org JSON-LD Preview

Operators and owning merchants can inspect the C6J schema.org JSON-LD preview through: GET /v1/commerce/merchants/{merchant_id}/schemaorg-jsonld-preview The endpoint is tenant-scoped and sandbox-only. It returns a preview-only https://schema.org JSON-LD graph generated from canonical Grantex merchant, catalog, and readiness state. The adapter serializes only sanitized evidence for schema.org Product, Offer, MerchantReturnPolicy, and OfferShippingDetails fields. It does not expose exact internal tenant, merchant, product, variant, or SKU IDs. The response includes explicit non-enabling flags:

• schemaorg_publication_enabled: false
• public_discovery_enabled: false
• checkout_payment_enabled: false
• live_provider_enabled: false
• live_plural_enabled: false
• production_allowlist_written: false
• certification_claims: []

CommerceAgent and service callers are denied. Live merchants return a blocking error. Missing or unsafe catalog evidence is omitted and reported through blockers, omitted_types, and remediation_items; clients must not fill in missing seller, product, price, inventory, shipping, refund, launch, payment, or certification facts.

​

UCP-Style Capability Profile Preview

Operators and owning merchants can inspect the C6K UCP-style capability profile preview through: GET /v1/commerce/merchants/{merchant_id}/ucp-capability-profile-preview The endpoint is tenant-scoped and sandbox-only. It returns services, capabilities, transports, controls, blockers, and evidence summary fields from canonical Grantex merchant/catalog/readiness state. Every capability ID uses the Grantex-owned namespace: dev.grantex.commerce.discovery.preview The endpoint must not publish dev.ucp.*, must not claim UCP certification, and must not enable a public discovery route. Response controls explicitly keep public discovery, checkout/payment creation, live provider access, live Plural, production allowlist writes, UCP publication, and UCP certification disabled. Read-only discovery capabilities can be marked preview_available when Grantex has public-safe profile and catalog evidence. Checkout, payment, fulfillment, refund/return execution, provider credentials, and live paths remain blocked metadata only.

​

ACP-Style Checkout Shape Preview

Operators and owning merchants can inspect the C6L ACP-style checkout shape preview through: GET /v1/commerce/merchants/{merchant_id}/acp-checkout-shape-preview The endpoint is tenant-scoped and sandbox-only. It reads canonical Grantex cart, payment intent, consent, Commerce Passport, and active policy evidence, then returns ACP-style cart and checkout mapping objects as preview metadata. It does not call the payment provider and does not reuse the runtime checkout/payment creation handlers. The response includes explicit non-enabling controls:

• acp_publication_enabled: false
• acp_certification_claim: none
• public_checkout_enabled: false
• payment_intent_creation_enabled: false
• checkout_link_creation_enabled: false
• provider_call_enabled_by_preview: false
• live_payment_enabled_by_preview: false
• live_plural_enabled_by_preview: false

Checkout mapping stays blocked when granted checkout consent, an unrevoked checkout Commerce Passport, an active policy, cart evidence, or sandbox payment intent evidence is missing. Unsupported fields such as public checkout URLs, provider payment references, provider metadata, live execution, fulfillment, and refunds/returns are represented as explicit blockers.

​

AP2-Style Evidence Preview

Operators and owning merchants can inspect the C6M AP2-style evidence preview through: GET /v1/commerce/merchants/{merchant_id}/ap2-evidence-preview The endpoint is tenant-scoped, sandbox-only, deterministic, and unsigned. It reads canonical Grantex evidence from Commerce Passport, consent record, policy decision, cart snapshot hash, amount cap, merchant state, agent identity, audit reference, and existing idempotency evidence. The response is protocol packaging evidence only. It is not AP2 certification, is not AP2 publication, is not a signed production mandate, does not submit to a payment network, and does not enable checkout/payment creation, live payment, live Plural, public discovery, provider calls, provider credentials, production configuration, or production allowlists. Required evidence gaps return status: blocked with explicit blockers. The preview exposes hashes and presence flags where possible, but does not expose tenant IDs, exact merchant IDs, passport JTIs, consent record IDs, audit event IDs, provider references, raw line items, raw payloads, JWTs, idempotency keys, secrets, or private configuration.

​

Existing-System Connector Registry

Operators and owning merchants can manage the C6N connector registry through:

• POST /v1/commerce/connectors
• GET /v1/commerce/connectors
• PATCH /v1/commerce/connectors/{connector_key}

The registry is a metadata-only foundation for existing merchant systems: manual maintenance, CSV, custom API, Shopify, WooCommerce, Magento, ERP, billing, OMS, WMS, logistics, CRM/support, and payment provider. It records connector type, display name, source-of-truth domains, source priority, sync status, health state, last sync timestamps, stale thresholds, webhook source references, and conflict blockers. The source precedence model covers catalog, price, inventory, order, fulfillment, refund, settlement, and support. List responses derive the primary connector per domain and include stale/conflict blockers instead of publishing stale facts as if they were current. This registry does not store credentials, raw payloads, provider metadata, private URLs, production config, or secrets. It does not call Shopify, WooCommerce, Magento, custom APIs, ERP, billing, OMS, WMS, logistics, CRM/support, payment providers, Plural, Stripe, or Pine. It also does not enable checkout/payment creation, fulfillment, refund execution, live payments, live Plural, public discovery, production Commerce V1, or protocol certification. AgenticOrg must never call merchant private systems directly. AgenticOrg reads only Grantex-grounded commerce APIs; Grantex owns connector metadata, source precedence, freshness, and blocker evidence.

​

Auth And Caller Model

Commerce callers are modeled as agents operating for a tenant, merchant, and user. A caller must be authenticated through an approved Grantex auth source in runtime configuration. Auth material is runtime-sensitive and must not be committed or printed. The important IDs are not equivalent: Synthetic tenant, merchant, user, product, and variant IDs may appear in evidence when they are non-production fixtures. Usable passports, bearer tokens, idempotency key values, secrets, and provider credentials remain sensitive.

​

Consent-First Checkout Sequence

During fixture-backed smoke runs, AgenticOrg may already have a checkout passport exported by the Grantex smoke runner. In that case, AgenticOrg evidence treats consent_exchange as skipped only when the blocker is exactly preexported_checkout_passport_without_granted_consent_fixture.

​

Payment Intent Shape

Payment intent calls must send only fields supported by the Grantex Commerce contract. Local fixture guardrail data, such as amount cap metadata used by AgenticOrg preflight checks, must not be forwarded to Grantex as arbitrary top-level request fields. Keep idempotency values out of docs and logs. Evidence may record that an idempotency mechanism was used, but never the value.

​

Webhooks And Replay

Grantex owns provider webhook ingestion, verification, replay controls, and reconciliation status. Current public smoke evidence uses the mock-provider path only. The Plural hosted-checkout adapter verifies the documented HMAC webhook scheme behind the provider abstraction, but failed webhook replay remains operator-only and mock-provider-only until non-mock replay retention and operator controls are separately approved. Replay safety rules:

• do not log raw provider payloads;
• do not store or expose webhook secrets in documentation;
• preserve original signature metadata only in protected runtime storage;
• replay only through operator-approved controls;
• treat live provider replay as blocked until provider/legal/ops gates pass.

​

Error Handling

Commerce clients should treat validation and policy failures as explicit outcomes, not retry storms. Important classes include:

​

Shopify Live Pilot And Sandbox

Use mock-provider/internal sandbox flows for local development, tests, and feature work. The production live pilot uses the approved Shopify merchant mch_shopify_mgx0n6_22 from mgx0n6-22.myshopify.com, with five imported products and five variants available through Grantex catalog search. The Plural adapter can be exercised only with stored credentials and explicit runtime flags. Current production credentials authenticate against Plural UAT-compatible rails, so developer docs must not claim production Plural settlement or provider certification. Approved temporary Option A smoke used isolated Cloud Run, Cloud SQL, Redis, smoke secrets, and mock provider resources that were deleted immediately after evidence capture. Developers should use:

• docs/guides/commerce-v1-repeatable-option-a-smoke-workflow.md for the approval-gated smoke path;
• docs/examples/commerce-option-a-smoke.runbook.json for runbook fields;
• the internal Option A smoke evidence record (operator-internal, kept in docs/internal/commerce-v1/ and available to authorized reviewers via security@grantex.dev);
• the internal production-discovery readiness record (same access path) for the current posture.

​

Live-Readiness Guard

The live commerce guard exposes a machine-readable readiness snapshot for operators and tests. The snapshot reports only booleans, requirement keys, env names, and blocker strings. It must not contain tokens, passports, credentials, provider payloads, idempotency values, DB URLs, Redis URLs, or raw webhook material. Live checkout and live Plural still require the master live-mode flag, the Plural live flag, and every readiness acknowledgement. The approved Shopify pilot has those acknowledgements set in production. When any acknowledgement is absent in another environment or future rollout, live provider paths fail closed with live_readiness_blocked. Important acknowledgement names include COMMERCE_LIVE_LEGAL_APPROVED, COMMERCE_LIVE_PROVIDER_CONTRACT_CONFIRMED, COMMERCE_LIVE_PLURAL_SANDBOX_E2E_PASSED, COMMERCE_LIVE_PLURAL_WEBHOOK_SIGNATURE_CONFIRMED, COMMERCE_LIVE_INDIA_RESIDENCY_CONFIRMED, COMMERCE_LIVE_FINAL_USER_CONFIRMATION_APPROVED, COMMERCE_LIVE_PILOT_MERCHANT_APPROVED, COMMERCE_LIVE_HOSTED_OACP_E2E_PASSED, COMMERCE_LIVE_SECRETS_REVIEWED, COMMERCE_LIVE_AUDIT_APPEND_ONLY_VERIFIED, COMMERCE_LIVE_OPERATOR_RUNBOOK_APPROVED, and COMMERCE_LIVE_ROLLBACK_OWNER_ASSIGNED. This guard remains the release boundary for future merchants and providers. Public docs, demos, and AgenticOrg handoffs must distinguish the approved Shopify live pilot from broader merchant self-service or provider settlement claims.

​

Controlled Until Future Approval

• Broad self-serve merchant production onboarding.
• External certification or standards conformance claims.
• Production Plural settlement claims while only UAT-compatible credentials are validated.
• Direct provider calls from AgenticOrg commerce.
• Public docs that imply AP2, UCP, ACP, Plural production settlement, payment-provider certification, or external pilot certification beyond the approved Shopify live pilot.