Merchant Services Enterprise API Documentation

Merchant Services exposes catalog, checkout, order, procurement, webhook, UCP, and MCP capabilities through one store-scoped authorization model. This document is the primary map of the public integration contract. Detailed payload and operational guides are linked from each section.

Base URLs

Surface	Base URL
Catalog REST API	https://merchant.thyris.cloud/api/v1/catalog
Procurement REST API	https://merchant.thyris.cloud/api/v1/procurement
UCP-compatible API	https://merchant.thyris.cloud/api/protocols/ucp
Merchant MCP	https://merchant.thyris.cloud/mcp
Inbound webhooks	Environment-specific webhook host supplied during onboarding

Use the staging hosts supplied by Thyris during integration and UAT. Do not send test products, carts, or procurement orders to a production store.

Authentication

Every business endpoint requires a developer API key created in the Merchant Dashboard. The recommended header is:

Authorization: Bearer tr_live_your_key_here

Supported integration-specific alternatives are:

x-api-key: tr_live_your_key_here
X-Catalog-API-Key: tr_live_your_key_here
X-Procurement-API-Key: tr_live_your_key_here

Use only the header appropriate to the integration surface. The key's merchant, network, custom-store, or single-store scope is enforced on the server. A request cannot expand that scope by sending a different storeId.

See Authentication and Scopes for key creation, expiration, revocation, deletion, and scope selection.

Request Conventions

• Send JSON request bodies with Content-Type: application/json.
• Use the Thyris UUID returned by the API for resource path parameters.
• Use stable sku or externalId values for idempotent product synchronization.
• Send monetary currency as an ISO 4217 code such as USD or EUR.
• Treat the service response as authoritative for price, inventory, cart, order, and procurement status.
• Keep API keys in backend services. Never embed them in a browser or mobile application.

The complete required and optional field matrix is available in Request Field Requirements.

Response Conventions

Successful operations use a JSON envelope containing success and, where applicable, data:

{
  "success": true,
  "data": {
    "id": "resource_uuid"
  }
}

Clients must evaluate the HTTP status before reading data. Do not treat a parseable JSON body as proof of success.

Catalog API

The Catalog API manages stores, sellable products, carts, checkouts, and customer orders.

Method	Path	Purpose
GET	/api/v1/catalog/stores	List stores visible to the API key.
GET	/api/v1/catalog/products	List or search products.
POST	/api/v1/catalog/products	Create a product or upsert by stable identity.
GET	/api/v1/catalog/products/{productId}	Read one product.
GET	/api/v1/catalog/product-details?catalogId={catalogId}	Read complete authorized details directly, without a Flow.
PATCH	/api/v1/catalog/products/{productId}	Update product data, price, or inventory.
DELETE	/api/v1/catalog/products/{productId}	Delete one product.
GET	/api/v1/catalog/carts	List non-archived carts by default; status=archived reads history.
POST	/api/v1/catalog/carts	Create a checkout-ready cart.
POST, PATCH, DELETE	/api/v1/catalog/carts/items	Idempotent single-item or atomic bundle mutation.
POST	/api/v1/catalog/carts/clear	Clear a cart without a checkout.
POST	/api/v1/catalog/carts/archive	Permanently archive a cart.
GET	/api/v1/catalog/orders	List or search orders.
POST	/api/v1/catalog/orders	Complete an order from a checkout.
GET	/api/v1/catalog/orders/{orderId}	Read an order by UUID, public ID, or checkout ID.
PATCH	/api/v1/catalog/orders/{orderId}	Update allowed order fields or status.

Product Upsert Example

This operation creates a product when no matching identity exists and updates it when sku or externalId matches a product in the same store.

POST /api/v1/catalog/products
Authorization: Bearer tr_live_your_key_here
Content-Type: application/json

{
  "storeId": "STORE_UUID",
  "sku": "HOODIE-BLK-M",
  "externalId": "erp-product-1042",
  "name": "Black Hoodie / Medium",
  "price": 49.90,
  "currency": "USD",
  "status": "active",
  "inStock": true,
  "inventoryQuantity": 12,
  "imageUrl": "https://cdn.example.com/hoodie.png",
  "productUrl": "https://store.example.com/products/hoodie"
}

storeId, name, and price are required. Stable identity fields are strongly recommended for repeatable synchronization. See the Catalog REST API for product, cart, and order payloads.

Procurement API

Procurement resources represent suppliers, merchant inputs, stock policies, quote-request workflows, and procurement orders. They are separate from customer-facing catalog products.

Method	Path	Purpose
GET	/api/v1/procurement/stores	List accessible procurement stores.
GET	/api/v1/procurement/suppliers	List suppliers.
POST	/api/v1/procurement/suppliers	Create a supplier.
GET	/api/v1/procurement/inventory	List or search procurement inputs.
POST	/api/v1/procurement/inventory	Create an inventory input and policy.
PATCH	/api/v1/procurement/inventory/{itemId}	Update an inventory input.
GET	/api/v1/procurement/orders	List procurement orders.
POST	/api/v1/procurement/orders	Create an order or quote request.
PATCH	/api/v1/procurement/orders/{orderId}	Update a supported order status.
POST	/api/v1/procurement/quotes	Deprecated and intentionally rejected.

Procurement Order Example

Creating an order with status set to requested starts the configured supplier quote-request workflow. Supplier quote states are controlled by the supported intake flow and cannot be set manually.

POST /api/v1/procurement/orders
Authorization: Bearer tr_live_your_key_here
Content-Type: application/json

{
  "storeId": "STORE_UUID",
  "supplierId": "SUPPLIER_UUID",
  "status": "requested",
  "source": "api",
  "reason": "Packaging stock is below its safety level.",
  "currency": "USD",
  "items": [
    {
      "inventoryItemId": "INVENTORY_ITEM_UUID",
      "name": "Shipping Box 12x10",
      "quantity": 1000,
      "unitCost": 0.42,
      "currency": "USD"
    }
  ]
}

See the Procurement REST API for supplier, inventory, order, and status contracts.

Inbound Webhooks

Inbound webhooks let an approved external system push changes without polling the REST APIs.

Path	Supported operations
/webhooks/catalog	Single product upsert, batch product upsert, and product deletion.
/webhooks/procurement	Supplier updates, inventory updates, and procurement order requests.

Authenticate the webhook request with the same scoped developer key model. Include a stable source identity so a retried delivery targets the same business record. product.inventory.updated carries an absolute current-stock snapshot. Cart item and bundle events, cart archive, and optional inbound version/timestamp are documented in Catalog Webhooks.

See Catalog Webhooks and Procurement Webhooks for event bodies, delivery responses, and receiver guidance.

Outbound Webhooks

Merchant Services sends outbound events to merchant-configured destinations after supported catalog, cart, order, and procurement changes. Write operations invoked through REST, UCP, the dashboard, or MCP can produce the same business event.

Receivers should:

• Verify the configured delivery authentication.
• Return a success response only after accepting the event durably.
• Deduplicate repeated deliveries using event identity, version, and timestamp where applicable.
• Process events asynchronously when business work can exceed the delivery timeout.
• Monitor failures and replay behavior.

UCP-Compatible APIs

The UCP surface provides protocol-compatible catalog and procurement operations while preserving the same store scope and business records.

Catalog

Method	Path
GET, POST	/api/protocols/ucp/catalog/products
GET, DELETE	/api/protocols/ucp/catalog/products/{productId}
POST	/api/protocols/ucp/catalog/carts
POST	/api/protocols/ucp/catalog/orders

Procurement

Method	Path
GET, POST	/api/protocols/ucp/procurement/suppliers
GET, POST	/api/protocols/ucp/procurement/inventory
POST	/api/protocols/ucp/procurement/orders
POST	/api/protocols/ucp/procurement/quotes (deprecated)

See UCP Catalog and UCP Procurement for mapping examples and compatibility notes.

Merchant MCP

Merchant MCP exposes approved catalog and procurement capabilities through JSON-RPC at /mcp.

POST /mcp
Authorization: Bearer tr_live_your_key_here
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Core tools include:

Tool	Purpose
catalog_list_stores	List stores allowed by the key.
catalog_search_products	Search available catalog products.
catalog_get_product_by_sku	Read a product by SKU.
catalog_get_product_details	Read complete product details by public catalogId or another supported identifier without a Flow.
catalog_upsert_product	Create or update a product.
catalog_create_cart	Create a cart from catalog IDs.
catalog_mutate_cart_items / cart_add_bundle	Mutate open-cart items or an atomic bundle.
catalog_archive_cart	Permanently archive a cart.
catalog_complete_order	Complete an order from checkout state.
procurement_list_inventory	Search procurement inputs.
procurement_create_supplier	Create a supplier.
procurement_create_inventory_item	Create an inventory input and policy.
procurement_create_order	Start a procurement order or quote request.
procurement_update_order_status	Advance a supported procurement state.

Call tools/list at connection time rather than hard-coding the tool schema. See Merchant MCP for full arguments and safety requirements.

Status Codes

Status	Meaning
200	Successful read or update.
201	Resource created.
400	Invalid JSON, missing field, or unsupported state transition.
401	API key is missing, invalid, expired, or revoked.
403	The key is valid but cannot access the requested store or record.
404	The requested resource does not exist in the allowed scope.
409	Identity or resource-state conflict.
429	Request rate exceeded.
500	Unexpected service failure.

Postman Companion Collection

The documentation above is the integration contract. Postman is an optional execution aid for development and UAT.

Download the Merchant Services Postman collection

After importing it, set baseUrl, webhookBaseUrl, apiKey, and storeId. Use separate collection copies or environments for staging and production so credentials and resource IDs cannot be mixed.