Merchant Readiness Checklist

This checklist helps a merchant confirm that its own systems are ready for Thyris Merchant Services and the Thyris Agentic Commerce platform.

Thyris Merchant Services is the merchant readiness layer for agentic commerce and agentic procurement. The goal is to make merchant catalog, checkout, order, supplier, inventory, quote, and procurement data available through secure, scoped, observable APIs and tools.

Use it before implementation starts and again before production launch.

Readiness Levels

Level	Meaning
POC-ready	Merchant can expose enough catalog, cart, checkout/order, and optional procurement capabilities for a controlled proof of concept.
Integration-ready	Merchant has stable APIs, credentials, test data, supplier/order data where needed, error handling, and operational ownership.
Production-ready	Merchant has monitoring, retry policy, security controls, compliance alignment, support processes, and production ownership for catalog and procurement flows.

Thyris Merchant Services Readiness Scope

Domain	Merchant Should Be Able To Provide
Catalog readiness	Product identity, product details, price, currency, stock, variants, images, and source-system update signals.
Commerce readiness	Cart behavior, checkout handoff, payment ownership, order creation, inventory deduction, order status, and post-purchase updates.
Procurement readiness	Supplier records, procurement inventory, reorder policies, quote request rules, approval rules, purchase order states, and receipt workflows.
Agentic access readiness	Approved MCP/UCP/API scopes, stable tool behavior, safe fields for agent responses, and no secrets in agent-visible data.
Operational readiness	Staging and production credentials, monitoring, retry and replay process, escalation owner, and credential rotation.

Minimum POC-Ready Capabilities

1. Product Catalog Discovery

The merchant should be able to provide structured product data.

Required:

Capability	Notes
Product list/export	API, file export, PIM feed, ecommerce platform API, or webhook feed.
Stable product identity	SKU and/or external product ID.
Product name	Required by Thyris product upsert.
Price	Required by Thyris product upsert.
Currency	Recommended. Must be 3 letters in Thyris.
Stock status	Recommended for agent/cart flows.
Inventory quantity	Recommended for cart/order validation.
Product URL	Recommended for user-facing discovery.
Image URL	Recommended for catalog quality.

Recommended:

Capability	Notes
Category and brand	Map to otherDetails.category and otherDetails.brand.
Tags/attributes	Map to otherDetails.tags or structured otherDetails.
Variant data	Size, color, option, variant SKU, variant external ID.
Updated timestamp	Useful for incremental sync.
Deleted/archived signal	Needed to remove or archive products in Thyris.

Questions to answer:

• What is the source of truth for products?
• Does every product have a stable SKU or external ID?
• Are variants separate records or nested under a parent product?
• How are out-of-stock, discontinued, and draft products represented?
• How often does product data change?
• Can the source system send incremental changes?

Agentic Commerce Readiness

The merchant should identify what an agent is allowed to do and which system owns each action.

Required decisions:

• Which products may be discovered by an agent.
• Which product fields may be shown to a customer or buyer.
• Whether an agent may create a cart.
• Whether an agent may complete an order, create a checkout handoff, or only prepare a quote/order draft.
• Which actions require human approval.
• Which errors should be shown to the user and which should be handled internally.

Recommended controls:

Control	Notes
Agent-visible catalog policy	Define which fields are safe for product discovery and recommendation.
Scoped API keys	Use store or custom-store scopes for agent/MCP access.
Tool allowlist	Enable only the MCP or UCP operations needed for the flow.
Approval gates	Require approval for high-value orders, restricted categories, or procurement orders.
Audit trail	Keep records of agent-triggered cart, order, quote, and procurement actions.

Questions to answer:

• Can agents show all active products or only a curated subset?
• Are price, stock, delivery estimate, and promotion fields reliable enough for agent responses?
• Which fields must never be returned to an agent or end user?
• What is the maximum order value or quantity an agent may initiate without approval?
• Who reviews failed or suspicious agent-triggered actions?

Cart And Add-To-Cart Capabilities

The merchant should know whether cart creation happens inside Thyris, inside the merchant platform, or both.

Required for Thyris cart flow:

Capability	Notes
Product availability data	Product must be active and in stock.
Inventory quantity	Used to reject insufficient quantity.
Store-level currency	Used for cart totals.
Checkout handoff decision	Decide where the final checkout happens.

If merchant owns cart creation:

Capability	Notes
Add-to-cart API	Merchant endpoint that accepts product/variant identity and quantity.
Cart read API	Ability to retrieve cart state.
Cart update/clear API	Optional, but useful for agent flows.
Cart expiration rules	Required for predictable checkout behavior.

Questions to answer:

• Should Thyris create carts, or should Thyris call the merchant cart API?
• Which identifier should be used for cart lines: SKU, external ID, variant ID, or another ID?
• Can cart creation fail when inventory changes?
• Is tax/shipping estimated before checkout?
• How long does a cart remain valid?

Checkout And Payment Handoff

The merchant should define how checkout is completed.

Common models:

Model	Description
Thyris order completion	Thyris creates a cart and completes an order through catalog order APIs.
Merchant checkout URL	Thyris creates or receives a checkout URL and redirects/hands off the customer.
Merchant payment API	Merchant exposes payment/checkout APIs for programmatic order placement.
Hybrid	Thyris handles catalog/cart while merchant owns final payment and fulfillment.

Required decisions:

• Who owns payment authorization?
• Who creates the final merchant order?
• Who owns inventory deduction?
• What happens if payment succeeds but order creation fails?
• What happens if order creation succeeds but payment fails?

Data needed for order completion:

Field	Required By Thyris API	Recommended For Production
checkoutId	Yes	Yes
payment.id	No	Existing non-sensitive payment reference when available; otherwise Catalog generates one.
customer	Yes as object	Include name, email, phone when available.
shippingAddress	Yes as object	Include line1, city, country, postal code.
billingAddress	No	Recommended when billing differs.
payment.provider / payment.status	No	Include safe provider/status context; supplied status must be paid.

Post-Purchase Capabilities

Production integrations usually need post-purchase visibility.

Preferred capabilities:

Capability	Notes
Order status API or webhook	Confirm order state after completion.
Cancellation/refund flow	Required if customers can cancel or refund.
Shipment/tracking updates	Needed for customer support and agent follow-up.
Invoice/receipt link	Useful for customer service and compliance.
Return status	Recommended for retail/ecommerce flows.

Questions to answer:

• Can the merchant provide order status updates?
• Are order updates sent by webhook or pulled by API?
• What statuses exist in the merchant system?
• Who handles refunds and cancellations?
• How are tracking numbers and carrier data shared?

Procurement Readiness

If agentic procurement is in scope, the merchant should provide the supplier, inventory, quote, approval, and purchase-order data needed for replenishment flows.

Required for procurement POC:

Capability	Notes
Supplier list	Supplier name, contact, channel, status, currency, and lead-time data.
Procurement inventory	Item name, SKU or external ID, quantity on hand, reorder point, target stock level, and preferred supplier when available.
Reorder policy	Manual, threshold-based, percentage-based, or custom policy text that can be converted into an executable policy.
Quote request rules	Which orders can request supplier quotes and what approval is required.
Order lifecycle	Requested, quoted, approved, payment requested, paid, sent, confirmed, in transit, received, completed, cancelled, or blocked.

Recommended for production:

Capability	Notes
Supplier email handling	Supplier replies can be linked back to the correct order request and parsed into quote details.
Approval ownership	Define who approves quotes, payment requests, and final purchase orders.
Payment handoff	Decide whether payment is recorded, requested, or completed through an external provider.
Receiving process	Confirm who updates received quantities and closes the order.
Exception handling	Define what happens when supplier replies are missing, invalid, late, or unmatched.

Questions to answer:

• Which items are eligible for automatic or assisted reorder?
• Which suppliers can receive quote requests by email or API?
• What fields are required before a procurement order can be requested?
• What quote changes require revision before approval?
• Who can mark a procurement order as paid, sent, received, or completed?

Customer And Delivery Handling

The merchant should define what customer and delivery data is required.

Required decisions:

• Required customer fields.
• Required shipping address fields.
• Supported countries/regions.
• Delivery methods and service levels.
• Whether delivery fees are calculated before payment.
• Whether pickup, digital delivery, or no-shipping products exist.

Questions to answer:

• Does checkout require phone number?
• Does checkout require billing address?
• Are there country restrictions?
• Are there product-specific delivery restrictions?
• How are invalid addresses handled?

Operational Maturity

The merchant should identify who owns the integration after launch.

Required:

Item	Notes
Technical owner	Person/team responsible for API credentials and integration behavior.
Support owner	Person/team responsible for production incidents.
Staging environment	Strongly recommended before production.
Test API key	Separate from production.
Production API key	Stored securely.
Monitoring	API errors, webhook failures, order failures.
Runbook	How to rotate keys, pause sync, replay events, and recover failures.

Questions to answer:

• Who receives failed webhook alerts?
• Who can rotate API keys?
• How are integration changes deployed?
• Is there a staging environment with realistic product/order data?
• How are failed product syncs retried?

Security Requirements

Required:

Requirement	Notes
HTTPS	All production endpoints must use HTTPS.
Secret storage	API keys must be stored in backend secrets, not frontend code.
Least privilege keys	Use store or custom scope where possible.
Key rotation process	Needed for exposed or expired credentials.
Access logging	Track integration activity and errors.

Recommended:

Requirement	Notes
Separate staging/production keys	Avoid accidental production writes.
Webhook shared secret validation	Validate x-webhook-secret for outbound webhook receivers.
IP allowlisting	Optional, if supported by merchant infrastructure.
PII minimization	Send only customer fields required for checkout/order flow.

Reliability And Performance

Recommended expectations:

Area	Recommendation
API timeout	10 seconds or less for normal operations.
Webhook receiver timeout	Return 2xx within 10 seconds.
Retry behavior	Retry idempotent product upserts; be careful with carts/orders.
Batch size	Inbound webhook batch limit is 250 products.
Rate limiting	Merchant should identify expected product volume and sync frequency.
Idempotency	Use stable SKU/external ID for product sync.

Questions to answer:

• How many products will be synced?
• How many updates per hour/day are expected?
• Can the merchant system handle retries?
• Can failed events be replayed?
• What is acceptable sync delay?

Compliance Considerations

The merchant should confirm:

• What customer data may be shared.
• Whether payment data is handled directly or only payment references are shared.
• Data retention requirements.
• Regional compliance requirements.
• Audit/logging requirements.
• Whether production support can access customer/order records.

Do not send raw card data through catalog, webhook, MCP, or UCP APIs.

Merchant Evaluation Questions

Catalog

• What is the product source of truth?
• Can products be exported through API, webhook, or file?
• Which fields are guaranteed for every product?
• Are SKU and external IDs stable?
• How are variants represented?
• How are deleted products represented?
• How often does product data change?

Cart

• Should Thyris create carts or call a merchant cart API?
• What product identifier does the cart system require?
• Can the cart API validate stock and price?
• Can carts be cleared or updated?
• How long do carts remain valid?

Checkout And Order

• Who owns final checkout?
• Does the merchant provide a checkout URL?
• Does the merchant provide an order creation API?
• Who deducts inventory?
• What customer/address fields are mandatory?
• What payment references are returned?

Post-Purchase

• Are order status updates available?
• Are shipment/tracking updates available?
• How are cancellations handled?
• How are refunds handled?
• Can order updates be sent by webhook?

Environments And Delivery

• Is there a staging environment?
• Is realistic test data available?
• Are staging and production credentials separate?
• What is the expected timeline for API access?
• Who approves production launch?

Security And Ops

• Where are API credentials stored?
• How are keys rotated?
• Who monitors failures?
• What logs are available?
• What is the incident escalation path?

Simple Scoring Rubric

Score	Meaning
0	Not available.
1	Manual or unclear.
2	Available but incomplete or unstable.
3	Available and usable for POC.
4	Production-ready with monitoring and ownership.

Suggested readiness scoring:

Area	Score 0-4
Catalog data quality
Stable product identity
Stock and inventory accuracy
Cart/add-to-cart capability
Checkout/order handoff
Post-purchase updates
Staging environment
Security/key handling
Monitoring and support

Typical Integration Timeline

Phase	Merchant Readiness Needed
Discovery	Merchant account, target stores, source systems, key stakeholders.
POC	API key, store ID, sample catalog, product sync path.
Integration	Stable product feed/API, cart/order decisions, webhook receiver/sender.
QA	Staging data, error cases, stock/price changes, order tests.
Production	Production keys, monitoring, support runbook, rollback plan.