# 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:

1. Install the official package shown in the current docs.
2. Configure merchant ID and API key from environment variables.
3. Mount middleware or routes server-side.
4. Verify public AI content routes and sitemap routes.
5. 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.

## Related Docs

- [SDK Documentation](https://joinhexagon.com/docs/sdk.md)
- [Commerce Platforms](https://joinhexagon.com/docs/commerce-platforms.md)
- [Implementation Checklist](https://joinhexagon.com/docs/implementation-checklist.md)
- [Security and Data Handling](https://joinhexagon.com/docs/security.md)