Request Field Requirements

This document lists required and optional values for each customer-facing integration request.

All authenticated requests require one API key header:

Authorization: Bearer tr_live_your_key_here

or:

x-api-key: tr_live_your_key_here

REST Catalog API

Base URL:

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

GET /stores

Lists stores available to the API key.

Required:

Location	Field	Notes
Header	API key	Required for authentication.

Optional:

Location	Field	Notes
Query	q	Search by store name, slug, or ID.

GET /products

Lists or searches products.

Required:

Location	Field	Notes
Header	API key	Required for authentication.

Optional:

Location	Field	Notes
Query	storeId	Limits results to one store. Store-scoped keys default to their bound store.
Query	q	Searches name, SKU, external ID, and catalog ID.

POST /products

Creates or upserts a product.

Required:

Location	Field	Type	Notes
Header	API key	string	Required for authentication.
Body	storeId	UUID string	Target store. Must be accessible by the API key.
Body	name	string	Product name.
Body	price	number	Must be 0 or greater.

Optional:

Field	Type	Default	Notes
sku	string	null	Idempotency key within the store. Max 120 chars.
externalId	string	null	Source system ID. Idempotency key within the store. Max 255 chars.
description	string	null	Product description.
currency	string	USD	Exactly 3 letters.
status	string	active	draft, active, or archived.
inStock	boolean	true	Stock availability.
inventoryQuantity	integer	0	Must be 0 or greater.
imageUrl	URL string	null	Legacy primary image URL; synchronized with the first imageUrls entry.
imageUrls	URL string[]	null	Optional ordered gallery, maximum 20 URLs. The first URL is primary.
productUrl	URL string	null	Public product page URL.
metadata	object	null	Internal integration metadata.
otherDetails	object	null	Flexible product attributes.
variants	array	[]	Product variant objects.

Required variant fields:

Field	Type	Notes
name	string	Variant name.
price	number	Must be 0 or greater.

Optional variant fields:

Field	Type	Default
sku	string	null
externalId	string	null
description	string	null
currency	string	USD
status	string	active
inStock	boolean	true
inventoryQuantity	integer	0
imageUrl	URL string	null
productUrl	URL string	null
otherDetails	object	null

GET /products/{productId}

Gets one product by Thyris product UUID.

Required:

Location	Field	Notes
Header	API key	Required for authentication.
Path	productId	Internal product UUID returned by create/list/search.

Optional: none.

GET /product-details

Gets the complete authorized product record directly from Merchant Catalog. No ACP Runtime or Flow execution is involved.

Required:

Location	Field	Notes
Header	API key	Required for authentication and merchant/store scope.
Query	One of catalogId, productId, sku, or externalId	Prefer the ten-digit catalogId returned by search.

Optional:

Location	Field	Notes
Query	storeId	Restricts lookup to one accessible store; recommended for SKU or external-ID lookup.

Product list, search, legacy lookup, and detail responses include store plus a public merchant object. The merchant object exposes only id, name, slug, description, logoUrl, websiteUrl, industry, and language.

storefront UI profile rule: a renderable product requires non-empty catalogId, name, price, currency, imageUrl, merchant.name, and merchant.logoUrl. merchant.websiteUrl is present in the response shape but may be null, because it cannot be guaranteed for every merchant. Enforce the required values at merchant onboarding/catalog synchronization or exclude the incomplete item from storefront render results.

PATCH /products/{productId}

Updates one product.

Required:

Location	Field	Notes
Header	API key	Required for authentication.
Path	productId	Internal product UUID.

Optional body fields:

Field	Type	Notes
storeId	UUID string	Move/update target store if key can access it.
sku	string or null	Replaces SKU.
externalId	string or null	Replaces external ID.
name	string	Replaces name.
description	string or null	Replaces description.
price	number	Replaces price.
currency	string	Exactly 3 letters.
status	string	draft, active, or archived.
inStock	boolean	Replaces stock status.
inventoryQuantity	integer	Replaces stock quantity.
imageUrl	URL string or empty string	Replaces image URL.
imageUrls	URL string[] or null	Replaces the ordered gallery; maximum 20 valid URLs. First URL becomes primary.
productUrl	URL string or empty string	Replaces product URL.
metadata	object or null	Replaces metadata.
otherDetails	object or null	Replaces flexible attributes.
variants	array	Replaces variants.

At least one body field should be provided.

inventoryQuantity replaces the current quantity with an absolute snapshot. It must not be interpreted as “subtract this amount.” Use source event/version metadata to prevent duplicate or out-of-order updates from changing stock twice.

DELETE /products/{productId}

Deletes one product by Thyris product UUID.

Required:

Location	Field	Notes
Header	API key	Required for authentication.
Path	productId	Internal product UUID.

Optional: none.

GET /carts

Lists carts.

Required:

Location	Field	Notes
Header	API key	Required for authentication.

Optional:

Location	Field	Notes
Query	storeId	Limits results to one store. Store-scoped keys default to their bound store.

POST /carts

Creates a checkout-ready cart.

Required:

Location	Field	Type	Notes
Header	API key	string	Required for authentication.
Body	storeId	UUID string	Target store.
Body	items	array	One or more cart items. Max 100 items.
Body item	catalogId	string	10 digit product catalog ID. Not the product UUID.
Body item	quantity	integer	Must be 1 or greater.

Optional:

Field	Type	Default	Notes
metadata	object	null	Internal cart metadata.
otherDetails	object	null	Channel/agent context.
Item metadata	object	null	Internal line-item metadata.
Item otherDetails	object	null	Line-item context.

POST/PATCH/DELETE /carts/items

Mutates an existing open cart after creation. POST adds items, PATCH replaces quantities, and DELETE removes lines. Single item fields and bundle items[] are both supported.

Required:

Location	Field	Type	Notes
Header	API key	string	Required for authentication.
Header	Idempotency-Key	string	Required for safe write replay.
Body	cartId	UUID string	Target cart.
Body	items[] or single catalogId/itemId	array/string	Bundle or single-item mutation.
Body item	quantity	integer	Required for add/update; must be 1 or greater.

Optional:

Field	Type	Notes
Body item metadata	object	Internal line metadata for add.
Body item otherDetails	object	Line context for add.
Body itemIds[]	array	Delete multiple lines by item UUID.

POST /carts/clear?cartId={cartId}

Clears cart line items only when no checkout ID exists.

Required:

Location	Field	Notes
Header	API key	Required for authentication.
Query	cartId	Internal cart UUID.

Optional: none.

POST /carts/archive?cartId={cartId}

Archives a cart permanently. Archived carts cannot be reopened or mutated.

Required:

Location	Field	Notes
Header	API key	Required for authentication.
Query or body	cartId	Internal cart UUID.

Optional: none.

GET /orders

Lists orders.

Required:

Location	Field	Notes
Header	API key	Required for authentication.

Optional:

Location	Field	Notes
Query	storeId	Limits results to one store.
Query	q	Searches order ID, checkout ID, and payment ID.

POST /orders

Completes an order from a checkout ID.

Required:

Location	Field	Type	Notes
Header	API key	string	Required for authentication.
Body	checkoutId	string	Checkout ID returned by cart creation.
Body	customer	object	Customer data.
Body	shippingAddress	object	Shipping address data.

Optional:

Field	Type	Default	Notes
billingAddress	object	null	Billing address data.
payment	object	generated reference	Optional safe payment reference. When omitted, Catalog generates an internal payment ID.
payment.id	string	generated	Existing non-sensitive payment reference when the caller has one.
payment.provider	string	omitted	Optional provider name inside the payment object.
payment.status	string	omitted	Optional; when supplied it must be paid.
metadata	object	null	Internal order metadata.
otherDetails	object	null	Integration-specific order data.

Recommended customer fields:

Field	Required By API	Notes
name	No	Strongly recommended.
email	No	Strongly recommended.
phone	No	Optional.

Recommended address fields:

Field	Required By API	Notes
line1	No	Strongly recommended.
city	No	Strongly recommended.
country	No	Strongly recommended. Use ISO country code when possible.
postalCode	No	Strongly recommended when applicable.

GET /orders/{orderId}

Gets one order.

Required:

Location	Field	Notes
Header	API key	Required for authentication.
Path	orderId	Internal order UUID, public orderId, or checkoutId.

Optional: none.

PATCH /orders/{orderId}

Updates order details or status.

Required:

Location	Field	Notes
Header	API key	Required for authentication.
Path	orderId	Internal order UUID, public orderId, or checkoutId.

Optional body fields:

Field	Type	Notes
status	string	completed or cancelled.
customer	object	Replaces customer data.
shippingAddress	object	Replaces shipping address.
billingAddress	object or null	Replaces billing address.
paymentDetails	object or null	Replaces payment details.
metadata	object or null	Replaces metadata.
otherDetails	object or null	Replaces other details.

At least one body field should be provided.

Inbound Catalog Webhook

Endpoint:

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

Product Create/Update/Upsert Events

Events:

• product.created
• product.updated
• product.upserted
• product.inventory.updated
• product.price.updated
• catalog.batch.upserted

Required:

Location	Field	Type	Notes
Header	API key	string	Required for authentication.
Body	event	string	One of the supported events.
Body	product or products	object or array	Single product or product array.
Product	storeId	UUID string	Target store.
Product	name	string	Required for create/update/upsert events.
Product	price	number	Required for create/update/upsert events.

Optional:

Field	Type	Notes
source	string	Source system label, for example shopify, erp, or pim.
direction	string	Defaults to inbound.
Product sku	string	Idempotency key.
Product externalId	string	Idempotency key.
Product description	string	Product description.
Product currency	string	Defaults to USD.
Product status	string	Defaults to active.
Product inStock	boolean	Defaults to true.
Product inventoryQuantity	integer	Defaults to 0.
Product imageUrl	URL string	Product image URL.
Product imageUrls	URL string[]	Ordered product gallery, maximum 20 valid URLs. First URL becomes primary.
Product productUrl	URL string	Product page URL.
Product metadata	object	Internal metadata.
Product otherDetails	object	Flexible attributes.
Product variants	array	Variant objects.

Batch requests use products and support up to 250 product objects.

Product Delete Events

Events:

• product.deleted
• catalog.batch.deleted

Required:

Location	Field	Type	Notes
Header	API key	string	Required for authentication.
Body	event	string	Delete event.
Body	product or products	object or array	Single product identity or product identity array.
Product	storeId	UUID string	Target store.
Product	sku or externalId	string	At least one identity is needed to find the product.

Optional:

Field	Type	Notes
source	string	Source system label.
Product sku	string	Optional only if externalId is present.
Product externalId	string	Optional only if sku is present.

Outbound Webhook Receiver

Outbound webhooks are sent by Thyris to a merchant receiver URL configured in the dashboard.

Receiver URL requirements:

Field	Required	Notes
Destination URL	Yes	Public HTTPS URL. Private/internal URLs are blocked.
Events	Yes	At least one outbound event must be selected.
Secret	No	Sent as x-webhook-secret when configured.

Headers sent by Thyris:

Header	Required	Notes
Content-Type: application/json	Yes	Always sent.
x-webhook-secret	No	Sent only if configured.

Receiver response:

Requirement	Notes
2xx status	Treated as successful delivery.
Response within 10 seconds	Longer requests time out and are logged as failed.

Outbound payloads always include:

Field	Type	Notes
event	string	Event name.
direction	string	outbound.
source	string	Source that triggered the event.
version	string	Webhook schema/source version combined with timestamp, for example catalog.v1@2026-09-12T18:00:00Z.
timestamp	string	RFC 3339 event timestamp.

Payload-specific fields:

Event Family	Required Payload Field
Product events	product
Cart/checkout events	cart when emitted by cart flow
Order events	order

REST Procurement API

Base URL:

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

GET /stores

Lists stores available to the API key.

Required:

Location	Field	Notes
Header	API key	Required for authentication.

GET /suppliers

Required:

Location	Field	Notes
Header	API key	Required for authentication.

Optional:

Location	Field	Notes
Query	storeId	Limits results to one store.
Query	limit	Maximum result count.

POST /suppliers

Required:

Location	Field	Type	Notes
Header	API key	string	Required for authentication.
Body	storeId	UUID string	Target store.
Body	name	string	Supplier name.

Optional fields: domain, logoUrl, websiteUrl, externalId, channel, status, reliabilityScore, leadTimeDays, activeItems, currency, supportedCurrencies, capabilities, endpoints, contact, metadata.

Supplier currency is the primary currency used for supplier order requests and inbound supplier quote processing. supportedCurrencies is an array of 3-letter currency codes; the primary currency is always included.

GET /inventory

Required:

Location	Field	Notes
Header	API key	Required for authentication.

Optional:

Location	Field	Notes
Query	storeId	Limits results to one store.
Query	q	Searches name, SKU, external ID, and procurement item ID.
Query	limit	Maximum result count.

POST /inventory

Required:

Location	Field	Type	Notes
Header	API key	string	Required for authentication.
Body	storeId	UUID string	Target store.
Body	name	string	Inventory item name.

Optional fields: preferredSupplierId, sku, externalId, description, imageUrl, imageUrls, itemUrl, category, targetProduct, status, quantityOnHand, reorderPoint, targetStockLevel, reorderThresholdPercent, maxOrdersPerWeek, autoReorderEnabled, customOrderPolicy, leadTimeDays, unitCost, currency, aiSignal, metadata, otherDetails. imageUrls is an ordered array of at most 20 valid URLs; its first item is synchronized to imageUrl. reorderQuantity is legacy/system-managed; order quantity is calculated from target stock and current stock.

PATCH /inventory/{itemId}

Required:

Location	Field	Notes
Header	API key	Required for authentication.
Path	itemId	Internal procurement inventory item UUID.

Optional body fields are the same as POST /inventory.

GET /orders

Required:

Location	Field	Notes
Header	API key	Required for authentication.

Optional:

Location	Field	Notes
Query	storeId	Limits results to one store.
Query	limit	Maximum result count.

POST /orders

Required:

Location	Field	Type	Notes
Header	API key	string	Required for authentication.
Body	storeId	UUID string	Target store.
Body	items	array	One or more order lines.
Body item	name	string	Line item name.
Body item	quantity	integer	Must be 1 or greater.

Optional fields: supplierId, status, source, reason, approvalRequired, eta, currency, metadata, otherDetails.

Use status=requested to start the supplier quote request workflow. Manual quote states (quote_requested, quote_received, pending_approval) are rejected; supplier quote states are created only through the supported quote intake flow.

Optional item fields: inventoryItemId, procurementItemId, unitCost, currency, metadata.

PATCH /orders/{orderId}

Required:

Location	Field	Notes
Header	API key	Required for authentication.
Path	orderId	Internal procurement order UUID.

Optional body fields: status, reason, approvalRequired, eta, metadata, otherDetails.

POST /quotes

Deprecated. This endpoint rejects manual quote creation. Create an order request and use the supported supplier quote intake flow.

Inbound Procurement Webhook

Endpoint:

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

Required:

Location	Field	Notes
Header	API key	Required for authentication.
Body	event	Event name.
Body	One of supplier, inventoryItem, or order	At least one supported payload object is required. quote payloads are rejected.

Procurement webhook payload object fields follow the REST Procurement API requirements above.

Outbound Procurement Webhooks

Outbound procurement webhooks require the same destination fields as outbound catalog webhooks: name, HTTPS URL, selected events, and optional secret.

Payload-specific fields:

Event Family	Required Payload Field
Supplier events	supplier
Inventory events	inventoryItem
Quote events	order, email, or quote
Procurement order events	order

UCP Catalog API

Base URL:

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

UCP endpoints use the same required and optional fields as the REST Catalog API:

UCP Endpoint	Same Requirements As
GET /products	REST GET /products
POST /products	REST POST /products
GET /products/{productId}	REST GET /products/{productId}
PATCH /products/{productId}	REST PATCH /products/{productId}
DELETE /products/{productId}	REST DELETE /products/{productId}
GET /carts	REST GET /carts
POST /carts	REST POST /carts
POST /carts/clear?cartId={cartId}	REST POST /carts/clear?cartId={cartId}
GET /orders	REST GET /orders
POST /orders	REST POST /orders
GET /orders/{orderId}	REST GET /orders/{orderId}
PATCH /orders/{orderId}	REST PATCH /orders/{orderId}

UCP Procurement API

Base URL:

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

UCP procurement endpoints use the same required and optional fields as the REST Procurement API:

UCP Endpoint	Same Requirements As
GET /stores	REST Procurement GET /stores
GET /suppliers	REST Procurement GET /suppliers
POST /suppliers	REST Procurement POST /suppliers
GET /inventory	REST Procurement GET /inventory
POST /inventory	REST Procurement POST /inventory
GET /orders	REST Procurement GET /orders
POST /orders	REST Procurement POST /orders
PATCH /orders/{orderId}	REST Procurement PATCH /orders/{orderId}
POST /quotes	Deprecated; quote creation is reserved for supplier email replies.

Merchant MCP

Endpoint:

https://merchant.thyris.cloud/mcp

All MCP JSON-RPC POST /mcp requests require:

Location	Field	Notes
Header	API key	Required for catalog and procurement tools.
Body	jsonrpc	Use 2.0.
Body	id	Request ID.
Body	method	JSON-RPC method, for example tools/call.

initialize

Required:

Field	Notes
jsonrpc	2.0.
id	Request ID.
method	initialize.
params.protocolVersion	MCP protocol version.
params.clientInfo.name	Client name.
params.clientInfo.version	Client version.

Optional: none for the provided Postman request.

tools/list

Required:

Field	Notes
jsonrpc	2.0.
id	Request ID.
method	tools/list.

Optional: none.

tools/call

Required wrapper fields:

Field	Notes
jsonrpc	2.0.
id	Request ID.
method	tools/call.
params.name	Tool name.
params.arguments	Tool arguments object.

Tool argument requirements:

Tool	Required Arguments	Optional Arguments
catalog_list_stores	none	none
catalog_search_products	none	query, storeId, limit, includeDraft
catalog_search	none	query, storeId, limit
catalog_get_product_details	One of catalogId, productId, sku, or externalId	storeId; recommended with sku or externalId
catalog_get_product	One of productId, sku, or externalId	storeId when using sku or externalId
catalog_upsert_product	storeId, name, price	sku, externalId, description, currency, status, inStock, inventoryQuantity, imageUrl, imageUrls, productUrl, metadata, otherDetails, variants
catalog_delete_product	productId	none
catalog_create_cart	storeId, items, item catalogId, item quantity	metadata, otherDetails, item metadata, item otherDetails
catalog_mutate_cart_items	operation, cartId, idempotencyKey	catalogId, itemId, quantity, items bundle array
catalog_clear_cart	cartId	none
catalog_archive_cart	cartId	none
catalog_complete_order	checkoutId, customer, shippingAddress	payment, payment.id, payment.provider, payment.status, billingAddress, metadata, otherDetails
procurement_list_stores	none	none
procurement_list_inventory	none	storeId, query, limit
procurement_create_inventory_item	storeId, name	preferredSupplierId, sku, externalId, description, imageUrl, imageUrls, itemUrl, category, targetProduct, status, quantityOnHand, reorderPoint, targetStockLevel, reorderThresholdPercent, maxOrdersPerWeek, autoReorderEnabled, customOrderPolicy, leadTimeDays, unitCost, currency, metadata, otherDetails
procurement_list_suppliers	none	storeId, limit
procurement_create_supplier	storeId, name	domain, logoUrl, websiteUrl, externalId, channel, status, reliabilityScore, leadTimeDays, activeItems, currency, supportedCurrencies, capabilities, endpoints, contact, metadata
procurement_list_orders	none	storeId, limit
procurement_create_order	storeId, items	supplierId, status, source, reason, approvalRequired, eta, currency, metadata, otherDetails
procurement_create_quote_order	Deprecated	Quotes are created only from supplier email replies.
procurement_update_order_status	orderId, status	Quote statuses are not manually writable.

MCP cart creation uses the 10 digit catalogId, not the Thyris product UUID.

For both catalog products and procurement inventory items, imageUrls is optional, ordered, limited to 20 valid URL strings, and uses its first entry as the primary imageUrl.