merchant integration.md
Merchant Integration Guide
This page describes the production shape of a Hexagon merchant rollout. It is intentionally implementation-oriented for coding agents.
Integration Goal
The integration should make the merchant's product catalog AI-readable, AI-channel-ready, measurable, and connected to purchase paths. Treat it as commerce infrastructure, not a one-time content export.
Required Inputs
A production integration usually needs access to:
- product catalog data
- prices and currency
- inventory or availability
- variants and options
- product images and canonical URLs
- categories, collections, tags, and product attributes
- shipping, fulfillment, and region constraints where relevant
- commerce events for attribution
- order routing or checkout destination rules where supported
The exact source depends on the merchant platform. Shopify may have a native path; custom platforms may require feed or API work; enterprise merchants may need scoped custom integration.
Data Freshness
Product recommendations are only useful if the underlying data is current. For each data type, define the update strategy:
| Data | Freshness Concern | Implementation Note |
|---|---|---|
| Product title and description | Moderate | Update on product edits or daily sync. |
| Price | High | Sync whenever prices change. |
| Inventory | High | Sync frequently or use live checks for low-stock products. |
| Variant availability | High | Keep variant state aligned with checkout. |
| Images | Moderate | Sync on product media changes. |
| Shipping constraints | High | Avoid recommending products the shopper cannot receive. |
Server-Side Boundary
All Hexagon credentials and commerce platform credentials must stay server-side. For browser or mobile surfaces, expose only application-owned endpoints that proxy safe operations.
Do not put these in client code:
HEXAGON_API_KEY- commerce platform access tokens
- payment credentials
- Meta or WhatsApp tokens
- provider secrets
- private catalog export URLs
SDK-Based Path
When the official SDK supports the merchant's framework, prefer it. Current Markdown SDK examples are published at https://joinhexagon.com/docs/sdk.md.
For Node.js and Next.js, the expected pattern is:
- Install the official package shown in the current docs.
- Configure merchant ID and API key from environment variables.
- Mount middleware or routes server-side.
- Verify public AI content routes and sitemap routes.
- Confirm catalog and attribution behavior in the Hexagon dashboard or rollout workflow.
Custom Backend Path
If the merchant framework is not covered by current SDK docs, do not invent package names or endpoint paths. Treat the rollout as custom:
- document the merchant platform
- document catalog data source and schema
- document authentication model
- document sync frequency
- document expected AI channels
- contact sales@joinhexagon.com for custom rollout requirements
Attribution Events
Attribution can include referrals, citations, product clicks, purchase events, and revenue. Implement attribution with approved SDK or server-side event flows. The merchant should be able to answer:
- which AI platform sent the shopper?
- which product was recommended?
- which prompt or recommendation context mattered, if available?
- did the shopper click, add to cart, or purchase?
- what revenue should be attributed to AI discovery?
Launch Verification
Before declaring a rollout complete:
- The merchant's product data path is live or explicitly scoped.
- Credentials are server-side.
- Public documentation/discovery files are reachable.
- Catalog sync health is visible.
- Pricing and availability are current enough for the use case.
- Each AI channel has an expected purchase-path behavior.
- Attribution has been tested end to end.
- Error handling covers missing products, stale inventory, unavailable channels, and auth failures.