Commerce V1 Developer Guide

Grantex Commerce REST/MCP model, consent/passport sequence, idempotency, webhooks, Shopify live-pilot usage, and provider boundaries.

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:

Area	Tool or API responsibility
Merchant profile	Fetch merchant policy and status metadata.
Catalog search	Search grounded merchant products.
Catalog get item	Retrieve a specific product or variant.
Inventory check	Confirm availability before cart or checkout.
Cart create	Create a cart draft from grounded catalog IDs.
Consent request	Ask for the user permission required for checkout.
Consent exchange	Exchange granted consent for a Commerce Passport when a granted consent fixture exists.
Payment intent	Create a provider-neutral payment intent with passport and policy checks.
Checkout create	Create a checkout handoff through Grantex.
Payment status	Poll Grantex payment status, not a provider directly.

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 Business Profile From OACP Artifacts

The UCP-style capability profile preview (C6K, Grantex-owned namespace dev.grantex.commerce.discovery.preview) and the ACP-style checkout shape preview (C6L) were removed. Grantex now renders the ucp member of a UCP business profile at a pinned release from the merchant’s issued OACP artifacts:

GET /v1/commerce/oacp/ucp-profile?tenant_id=&merchant_id=&seller_agent_id=&version=2026-04-08&served=&rest_endpoint=&identity_linking_scopes=

Callers: the AgenticOrg service token (scope commerce.oacp.ucp_profile.read, allow-listed tenant), an operator of the tenant, or the platform admin. version is 2026-04-08 (default) or 2026-08-25. served lists the dev.ucp.* capabilities the business host actually serves. A capability is rendered only when it is served and every OACP artifact family that backs it is issued, unrevoked and unexpired; everything else is returned in withheld with the reason. Only dev.ucp.* names appear, each entry declares the profile’s ucp.version, and spec / schema point at ucp.dev for that release. The host adds its own signing keys and serves the document at /.well-known/ucp, and must not publish it while publication_allowed is false. See OACP runtime authority and adapter mappings.

AP2-Mapped PaymentMandate

The C6M AP2-style evidence preview (GET /v1/commerce/merchants/{merchant_id}/ap2-evidence-preview) was removed; the route now returns 404. It produced deterministic, unsigned review metadata only. Its replacement is the AP2-mapped PaymentMandate issued through POST /v1/commerce/oacp/mandates/payment.

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 or Stripe. 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:

Identifier	Purpose
Tenant ID	Owns isolation and policy boundaries.
Merchant ID	Owns catalog, provider configuration status, and merchant policy.
Agent ID	Identifies the delegated agent allowed to use commerce tools.
User/principal	The person whose consent controls checkout.
Commerce Passport	Scoped, usable runtime material created after approved consent or smoke fixture export.

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:

Class	Expected handling
validation_failed	Fix request shape or unsupported field usage.
consent_not_granted	Do not proceed without granted consent or an approved checkout passport fixture.
consent_denied	Stop the checkout path.
Amount-cap or policy breach	Fail safely before payment/provider work.
Disabled merchant or untrusted agent	Stop and surface an operator-safe blocker.

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 [e-mail] or [e-mail]);
• 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.

Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: [e-mail] or [e-mail].