Integration Selection Guide

Use this guide to choose the best integration approach for the merchant's existing systems.

The right integration depends on where the merchant's product and procurement data live, how updates are published, who owns cart/checkout or supplier ordering, and whether agent/MCP or UCP channels are required.

Quick Decision Table

Merchant Situation	Recommended Integration	Why
ERP, PIM, ecommerce backend, or middleware can call external APIs	REST Catalog API	Direct, controlled, idempotent product sync using POST /api/v1/catalog/products.
ERP/PIM/ecommerce platform already supports outbound webhooks	Inbound Catalog Webhook	Best for event-driven product sync when the source system can push changes.
Merchant wants Thyris to notify its systems about catalog/cart/order events	Outbound Catalog Webhooks	Best for receiving events from Thyris into ERP, OMS, warehouse, CRM, or analytics systems.
Merchant or partner has UCP-compatible integration requirements	UCP Catalog API	Use UCP paths while keeping the same auth, scope, and payload rules.
Merchant wants managed model, agent client, or another agent client to use catalog tools	Merchant MCP	Best for agent tool access: search products, upsert products, create carts, complete orders.
Merchant wants to manage suppliers, components, packaging, raw materials, or services	REST Procurement API	Direct supplier, inventory input, quote, and purchase order workflows.
Supplier systems can push inventory, quote, shipment, or purchase order updates	Inbound Procurement Webhook	Best for event-driven procurement sync.
Merchant wants Thyris to notify supplier, ERP, or warehouse systems about procurement events	Outbound Procurement Webhooks	Best for supplier/order lifecycle notifications.
Procurement partner has UCP-compatible integration requirements	UCP Procurement API	Use UCP procurement paths while keeping the same auth and payload rules.
Merchant only has CSV/manual exports today	Start with REST API or inbound batch webhook through middleware	A small adapter can read files and call Thyris APIs.
Merchant has many stores/sub-merchants under one operator	REST API with merchant_network or custom key	Supports central sync while keeping scope controlled.
Merchant needs one pilot store first	REST API or webhook with store or custom key	Keeps blast radius small for POC.

Recommended Default

If the merchant has no strong preference, start with:

1. REST Catalog API for product sync.
2. Outbound Catalog Webhooks for order/cart notifications if needed.
3. REST Procurement API for supplier, inventory input, quote, and purchase order sync if the merchant has procurement workflows.
4. Outbound Procurement Webhooks for supplier/order notifications if needed.
5. Merchant MCP only when agent clients need tool access.
6. UCP only when UCP compatibility is explicitly required.

REST API is usually the simplest first integration because it is explicit, easy to test with Postman/scripts, and idempotent when sku or externalId is stable.

Choose REST Catalog API When

Use REST API if:

• The merchant can run backend code or middleware.
• ERP/PIM/ecommerce system can make authenticated HTTP requests.
• Product sync should run on a schedule.
• Product sync should be controlled by a job, worker, or integration service.
• The merchant needs clear retry behavior.
• The merchant wants to upsert products idempotently.

Best for:

• ERP integration.
• PIM integration.
• commerce platform/commerce platform/custom ecommerce adapters.
• Middleware such as Make, n8n, custom Node/Python jobs.
• Initial POC.

Primary endpoint:

POST /api/v1/catalog/products

Minimum required product fields:

• storeId
• name
• price

Strongly recommended:

• sku
• externalId
• currency
• inStock
• inventoryQuantity

Example architecture:

Choose Inbound Catalog Webhooks When

Use inbound webhooks if:

• The merchant source system already emits product events.
• The merchant wants near-real-time product sync.
• The merchant can configure a destination URL and auth header.
• Product create/update/delete events are already available.

Best for:

• ERP/PIM systems with webhook support.
• Ecommerce platforms that notify on product changes.
• Event-driven inventory or price updates.
• Batch product event pushes.

Primary endpoint:

POST https://webhooks.thyris.cloud/webhooks/catalog

Best event types:

Source Event	Thyris Event
Product created	product.created or product.upserted
Product updated	product.updated or product.upserted
Price changed	product.price.updated
Inventory changed	product.inventory.updated
Product deleted	product.deleted
Batch sync	catalog.batch.upserted
Batch delete	catalog.batch.deleted

Example architecture:

Choose inbound webhook over REST polling when the merchant source system can reliably push changes and retry failed deliveries.

Choose Outbound Catalog Webhooks When

Use outbound webhooks if the merchant wants to receive events from Thyris.

Common reasons:

• Merchant OMS needs order completion notifications.
• Merchant ERP needs catalog changes made in Thyris.
• Warehouse system needs cart/checkout/order events.
• Analytics system needs catalog or order events.
• Support system needs order status events.

Configured in:

Store > Catalog > Integrations > Webhooks

Destination requirements:

• Public HTTPS URL.
• Responds with 2xx within 10 seconds.
• Optional x-webhook-secret validation.
• Idempotent receiver behavior.

Example architecture:

Use outbound webhooks together with REST or inbound webhooks when the merchant needs two-way integration.

Choose UCP Catalog API When

Use UCP if:

• The merchant or partner specifically requires UCP-compatible endpoint paths.
• A UCP integration is being evaluated or implemented.
• Existing integration code expects /api/protocols/ucp/catalog/... paths.

UCP endpoints mirror REST API behavior:

/api/protocols/ucp/catalog/products
/api/protocols/ucp/catalog/carts
/api/protocols/ucp/catalog/orders

Same rules apply:

• Same API key auth.
• Same key scopes.
• Same required fields.
• Same product/cart/order behavior.

Choose UCP only when UCP compatibility matters. Otherwise REST API is simpler for most merchant backend integrations.

Choose REST Procurement API When

Use REST Procurement API if:

• The merchant needs to manage suppliers separately from sellable catalog products.
• ERP, supplier portals, warehouse tools, or purchasing systems can call authenticated HTTP APIs.
• The merchant tracks components, materials, packaging, services, or supplier-owned items needed to make or sell catalog products.
• Quote and purchase order lifecycle states matter.

Primary endpoints:

/api/v1/procurement/suppliers
/api/v1/procurement/inventory
/api/v1/procurement/quotes
/api/v1/procurement/orders

Example architecture:

Catalog products and procurement inventory are separate datasets. Catalog is what the merchant sells. Procurement is what the merchant buys or sources to operate, produce, package, fulfill, or sell.

Choose Procurement Webhooks When

Use inbound procurement webhooks when supplier or ERP systems can push procurement changes into Thyris.

Inbound endpoint:

POST https://webhooks.thyris.cloud/webhooks/procurement

Use outbound procurement webhooks when the merchant wants Thyris to notify another system about supplier, inventory, quote, purchase order, or shipment events.

Configured in:

Store > Procurement > Integrations > Webhooks

Example architecture:

Choose UCP Procurement API When

Use UCP procurement if:

• A procurement partner specifically requires UCP-compatible endpoint paths.
• Existing integration code expects /api/protocols/ucp/procurement/... paths.
• The merchant wants procurement inventory, suppliers, quotes, and orders over the UCP namespace.

UCP procurement endpoints mirror REST procurement behavior.

Choose Merchant MCP When

Use Merchant MCP if:

• managed model, agent client, or another MCP client needs to use merchant catalog tools.
• Agent workflows need product search.
• Agent workflows need to create carts or complete orders.
• Agent workflows need procurement inventory, supplier, order request, or purchase order tools. Supplier quotes should use the supported quote intake flow.
• A developer wants to expose controlled catalog tools instead of custom REST code.

MCP endpoint:

https://merchant.thyris.cloud/mcp

Available tools:

• catalog_list_stores
• catalog_search_products
• catalog_get_product
• catalog_upsert_product
• catalog_delete_product
• catalog_create_cart
• catalog_clear_cart
• catalog_complete_order
• procurement_list_stores
• procurement_list_inventory
• procurement_create_inventory_item
• procurement_list_suppliers
• procurement_create_supplier
• procurement_list_orders
• procurement_create_order
• procurement_create_quote_order (deprecated; quote creation is email-reply driven)
• procurement_update_order_status

Example architecture:

Use a store-scoped or custom-scoped key for MCP whenever possible.

Choose Scripts Or File-Based Adapter When

Use the sample scripts or a custom file adapter if:

• The merchant can export CSV/JSON but cannot call APIs directly.
• Product data is manually generated.
• A POC needs to start before full ERP/PIM access is available.

Recommended flow:

The sample scripts in Sample Scripts show this pattern with products.json.

Common Combination Patterns

ERP/PIM Scheduled Sync

Use:

• REST Catalog API
• Optional outbound webhooks for orders

Pattern:

Event-Driven Ecommerce Platform

Use:

• Inbound catalog webhooks
• Outbound order webhooks

Pattern:

Agentic Commerce Pilot

Use:

• REST API for product sync
• Merchant MCP for agent access
• Store-scoped API key

Pattern:

UCP Compatibility Pilot

Use:

• UCP Catalog API
• Optional REST API for setup/testing

Pattern:

Marketplace Or Franchise Network

Use:

• REST API or inbound webhooks
• merchant_network key for central operator
• custom key for limited vendor/system access

Pattern:

Integration Selection Questions

Ask these before choosing a path:

1. Where is the product source of truth?
2. Can that system call external REST APIs?
3. Can that system send webhooks?
4. Does the integration need real-time updates or scheduled sync?
5. Who owns cart creation?
6. Who owns final checkout and payment?
7. Does the merchant need UCP compatibility?
8. Does an agent/MCP client need direct tool access?
9. Is the integration one store, selected stores, or all merchant/sub-merchant stores?
10. Does the merchant need to receive order/cart events back?

Final Recommendation Matrix

Answer	Choose
"We have an ERP/PIM and can call APIs."	REST Catalog API
"Our platform sends webhooks on product changes."	Inbound Catalog Webhooks
"We need to receive order/cart updates from Thyris."	Outbound Catalog Webhooks
"We need UCP-compatible paths."	UCP Catalog API
"managed model/agent client/agent client should search or act on catalog."	Merchant MCP
"We only have files right now."	File adapter or sample scripts into REST API
"We are not sure yet."	Start with REST API and Postman/scripts POC