Getting Started

This guide explains the recommended integration flow for a merchant connecting product catalog data, carts, orders, webhooks, and agent access to the Thyris merchant platform.

Integration Surfaces

Thyris supports four catalog integration surfaces:

Surface	Use When
REST Catalog API	Your backend, ERP, PIM, ecommerce platform, or middleware will push and read catalog data directly.
Catalog Webhooks	Your system needs to send product changes into Thyris or receive Thyris catalog/cart/order events.
Merchant MCP	managed model, agent client, or another MCP client needs controlled access to catalog tools.
UCP Catalog API	You need the UCP-compatible catalog protocol endpoints.

Most merchants start with REST API product sync, then add outbound webhooks, then enable MCP or UCP when agent channels are ready.

Use Integration Selection Guide before implementation if the merchant is not sure whether ERP/PIM API sync, inbound webhooks, UCP, MCP, or a script-based adapter is the right path.

Recommended Rollout

1. Create or confirm the target merchant account.
2. Create or confirm the target store in the Merchant Dashboard.
3. Create a developer API key with the narrowest scope that fits the integration.
4. Call GET /api/v1/catalog/stores and confirm the expected store is visible.
5. Upsert a small test product with POST /api/v1/catalog/products.
6. Verify the product in the dashboard and through GET /api/v1/catalog/products.
7. Create a cart from the product's 10 digit catalogId.
8. Complete an order from the returned checkoutId.
9. Configure inbound product sync from the merchant source system.
10. Configure outbound webhook destinations if the merchant system needs change notifications.
11. Run the QA checklist in Testing and Troubleshooting.

See Dashboard Setup for step-by-step merchant, store, sub-merchant, and API key setup.

Before implementation starts, use Merchant Readiness Checklist to confirm that the merchant's own product, cart, checkout, order, security, and operations capabilities are ready.

Base URLs

Merchant Services platform:

https://merchant.thyris.cloud/app/merchant-services

REST catalog:

https://merchant.thyris.cloud/api/v1/catalog

UCP catalog:

https://merchant.thyris.cloud/api/protocols/ucp/catalog

Remote MCP:

https://merchant.thyris.cloud/mcp

Minimal Product Sync Example

curl -X POST "https://merchant.thyris.cloud/api/v1/catalog/products" \
  -H "Authorization: Bearer tr_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "storeId": "STORE_UUID",
    "sku": "HOODIE-BLK",
    "externalId": "shopify_product_123",
    "name": "Black Hoodie",
    "description": "A heavyweight black hoodie.",
    "price": 49.90,
    "currency": "USD",
    "status": "active",
    "inStock": true,
    "inventoryQuantity": 12,
    "imageUrl": "https://cdn.example.com/hoodie.png",
    "imageUrls": [
      "https://cdn.example.com/hoodie.png",
      "https://cdn.example.com/hoodie-back.png"
    ],
    "productUrl": "https://store.example.com/products/hoodie",
    "otherDetails": {
      "brand": "Example Brand",
      "category": "Apparel",
      "tags": ["hoodie", "black"]
    }
  }'

Successful response:

{
  "success": true,
  "mode": "created",
  "data": {
    "id": "product_uuid",
    "catalogId": "1234567890"
  }
}

mode is created for new products and updated for idempotent updates.

Important Concepts

• storeId is required when creating products, carts, and store-specific records.
• id is the Thyris product UUID.
• catalogId is a 10 digit agent-facing product identifier used for cart creation.
• sku and externalId are idempotency identifiers within the same store.
• otherDetails is the recommended place for flexible attributes such as brand, category, tags, color, size, material, or fulfillment rules.
• Product images are stored externally; Thyris stores the primary imageUrl and an optional ordered imageUrls gallery of up to 20 URLs.