Skip to main content

Thyris Merchant Services as a Merchant Integration Hub

Thyris Merchant Services is the integration hub between existing merchant systems and new customer or agent channels. It normalizes catalog and procurement capabilities while the merchant's current commerce platform, ERP, supplier workflow, and operational tools remain systems of record.

When to use this scenario​

Use this model when a team needs to:

  • Connect an existing commerce platform without replacing it.
  • Synchronize catalog or procurement data through stable contracts.
  • Receive commands and publish lifecycle events.
  • Support traditional applications and AI clients from the same merchant boundary.
  • Package a repeatable adapter for multiple stores.
  • Migrate an integration with a controlled cutover and rollback window.

Integration surfaces​

SurfaceBest fit
REST APIDirect application integration, scheduled synchronization, and controlled commands.
Inbound webhooksExternal product, inventory, supplier, or order instructions delivered to Thyris.
Outbound webhooksLifecycle events sent to ERP, commerce, supplier, or monitoring systems.
UCPProtocol-compatible catalog and procurement clients.
MCPBounded catalog and procurement tools for approved AI clients.
ExtensionsPackaged adapters that translate a supported external system into Thyris contracts.
Sample scriptsInitial contract testing and implementation examples.

Reference topology​

Contract design​

Before implementing a connector, define:

  • The source of truth for each resource and field.
  • Stable merchant, store, product, supplier, and order identifiers.
  • Create, update, deletion, and status-transition ownership.
  • Idempotency and deduplication behavior.
  • Authentication, scopes, secret rotation, and environment boundaries.
  • Retry timing, ordering expectations, dead-letter handling, and replay.
  • Reconciliation and rollback procedures.

Implementation journey​

1. Select the integration model​

Choose the smallest combination of REST, webhooks, UCP, MCP, or extensions that matches the systems involved. Avoid duplicating the same write ownership across channels.

2. Map source data​

Map merchant records into Thyris catalog and procurement contracts. Document transformations, defaults, required fields, enum handling, and unsupported source values.

3. Synchronize a controlled subset​

Begin with representative products, suppliers, or orders. Compare counts, identifiers, prices, inventory, status, and timestamps with the source system.

4. Test failure behavior​

Test invalid signatures, expired keys, missing scopes, duplicate events, out-of-order events, rate limits, partial updates, downstream outages, and replay after recovery.

5. Cut over deliberately​

Choose the point when the new integration becomes authoritative for each operation. Keep a rollback window, prevent dual writes, and reconcile the final state before closing the previous path.

6. Add agent access separately​

After the base integration is stable, expose only the required MCP or UCP operations to AI clients. Agent access should not bypass the source-system ownership and approval rules established for application integrations.

Success measures​

  • Synchronization success and latency
  • Duplicate and reconciliation exception rate
  • Percentage of records with stable external identifiers
  • Webhook delivery and replay success
  • Time required to recover from downstream failure
  • Contract-breaking change count
  • Agent operations completed without bypassing source ownership

Production controls​

  • Use separate credentials and endpoints for staging and production.
  • Verify webhook signatures and reject stale or malformed requests.
  • Make write operations idempotent where supported.
  • Keep integration-specific names out of normalized public contracts.
  • Monitor delivery failures and retain enough evidence for replay.
  • Version breaking schema or behavior changes.