Merchant setup checklist

The five phases

Want to see the result first? Nilgiri Tea House is a live example shop that went through phases 1 to 4 without a payment method.

Five phases from shop to sales

Connect your shop, connect to Grantex, publish your UCP profile and open sales channels. The fifth phase, agent-executed payment, stays off until a payment-provider sandbox run has passed. Buyers already pay on your own page once checkout is open.

Phases 1 to 3 are one page for a merchant: Sell Everywhere (/dashboard/sell-everywhere) takes you from a new shop to a published profile, with no step for your platform operator; see Sell everywhere. The Commerce Runtime page at /dashboard/commerce-runtime is the operator console for the same runtime. You need the administrator role or the merchant role. A few steps are done by your platform operator, the person who runs your AgenticOrg deployment. Those steps say so.

Phase 1. Connect your shop

Create your shopOwner: Merchant
On Sell Everywhere, choose your shop, or type a shop name and select Create shop. AgenticOrg creates the merchant and its id; you never type one.
Blocked / exception
Check that you have the merchant or administrator role.
Connect your catalogOwner: Merchant
Connect Shopify with the Admin API token of a custom app in your own store (read_products, read_inventory), or upload a CSV or JSON catalog. AgenticOrg encrypts the token and never shows it again. Then compare a few products, prices and stock levels with your store or file.
Blocked / exception
Every sync uses your own stored token; without one it stops with blocked_missing_shopify_credentials. A wrong store address or a bad file row stops the read and says which.
Write your policiesOwner: Merchant
Write your returns and shipping terms, and store pickup if you offer it. Without Shopify, also set one shipping fee per order, its currency and the countries you ship to; 0 ships free.
Blocked / exception
A shop without Shopify and without a shipping fee can offer buyers no shipping, so Sell everywhere stays off until it is set.
Set your order limitsOwner: Merchant
Set the largest single order, the most per day, the most items per order and your currency. Nothing is set for you, and the daily maximum must be at least the per-order maximum.
Blocked / exception
Without limits, Sell everywhere stays off.

Where buyers pay is the next step on the same page; the checklist covers it in phase 4, where checkouts end.

Phase 2. Connect to Grantex

Turn on Sell everywhereOwner: Merchant, then AgenticOrg
Choose your shop name, accept the network terms and turn it on. AgenticOrg enrols your tenant, merchant and catalog source with Grantex itself; nobody edits a list for your shop.
Blocked / exception
The switch stays off until your catalog, policies, shipping fee and limits are done (setup_incomplete names what is missing). Waiting means your deployment's Grantex cannot enrol tenants yet.
Request authorityOwner: AgenticOrg
Going live sends the Grantex authority request once by itself, and Grantex signs your catalog, prices, stock and policies. Your operator can also send it from Commerce Runtime.
Blocked / exception
A 202 answer means connector evidence is missing; read your catalog again first.
Verify and keep the factsOwner: AgenticOrg
AgenticOrg checks every signature, key, expiry and revocation slot before it keeps anything. The Verified catalog row then shows Done.
Blocked / exception
Verified catalog shows To do; select Publish to try again. A 422 artifact_verification_refused lists each refusal code, and nothing from that batch is kept.
Ask a test questionOwner: Merchant
Ask your seller agent "Which variants are in stock?" and check that the answer shows its source and freshness.
Blocked / exception
A missing answer means catalog, price or stock facts are missing; refresh them.

Phase 3. Publish your UCP profile

Your UCP profile tells buyer agents where your shop is and what it offers. It is served at https://<your shop host>/.well-known/ucp.

With Sell everywhere this phase runs by itself:

A shop with no address gets <your-shop>.agenticorg.ai. It needs no TXT record, because AgenticOrg owns that domain. At most 20 shops get one.
A missing signing key is created, and the profile is published as soon as nothing stands in the way.
The Shop profile row shows the exact reason when it waits. Select Publish to run the steps again.

For a host of your own, ownership is proved with a DNS TXT record. The Custom Domains page runs these steps for you:

The DNS TXT step

AgenticOrg gives you a TXT record name and value. You add it at your DNS provider. AgenticOrg looks it up and, on a match, records that you control the host.

Choose your shop hostOwner: Merchant
Ask AgenticOrg for a challenge for your host, for example shop.merchant.example. It returns a TXT record name and value.
Blocked / exception
An IP address or a single-word host is not accepted.
Add the DNS TXT recordOwner: Merchant
At your DNS provider, add the TXT record _agenticorg-ucp.shop.merchant.example with the value AgenticOrg gave you.
Blocked / exception
DNS changes can take time to spread; wait and try the check again.
Verify the hostOwner: AgenticOrg
Ask AgenticOrg to check the record. On a match it stores the proof and links the host to your merchant.
Blocked / exception
A host already linked to another tenant is refused.
Create your signing keyOwner: Merchant
AgenticOrg creates one signing key for your shop. Your profile publishes its public half. Rotated keys stay published for at least 7 days.
Blocked / exception
Publishing is refused with signing_key_missing until a key exists; Publish on Sell Everywhere creates it.
PublishOwner: Merchant
Record your opt-in to public discovery. The next Grantex authority request asks Grantex to allow discovery for this host.
Blocked / exception
Refusals name the reason, such as serving_host_not_attested.
Profile goes liveOwner: Platform operator
When the UCP profile switch is on and Grantex has issued an allowing discovery artifact, the profile is served.
Blocked / exception
The profile answers 404 until every condition holds; the UCP status view shows which one is missing.

Your host must also reach the AgenticOrg service with the original host name intact. The easiest way is the Custom Domains page. It runs the TXT step above for you, adds the CNAME record that routes the host, and follows the domain until its certificate is live. See Your own domain for buyer agents.

Phase 4. Open your sales channels

Each channel has its own switch. Turn on one, test it, then the next.

UCP checkoutOwner: Platform operator and merchant
The operator turns on UCP checkout and you issue each agent platform its own API key. Agents can then open checkouts at your /ucp address.
Blocked / exception
With the switch off, every checkout route answers 404, the network included.
ACP product feedOwner: Platform operator and merchant
The operator turns on the ACP feed. You export it as JSON, JSON Lines or CSV and upload the files where the agent platform asks.
Blocked / exception
The feed is refused until the catalog's verified facts are fresh.
ACP checkoutOwner: Platform operator and merchant
The operator turns on ACP checkout, you opt your shop in, and you issue the platform a key with ACP write access.
Blocked / exception
Without your opt-in your ACP routes answer 404.
MCP checkout toolsOwner: AgenticOrg, or the platform operator for your own install
Sell everywhere shops are served by the AgenticOrg server at https://mcp.agenticorg.ai/mcp, with nothing to set. For an MCP server of your own, set the address of your UCP profile on each install; its checkout tools appear only while your profile lists checkout.
Blocked / exception
No profile address, or checkout off, means no tools are registered.
Choose where buyers payOwner: Merchant
In the Payments step of Sell Everywhere, choose your own Shopify checkout, or your own Plural account (client ID, client secret and webhook secret, Sandbox or Production, then Test). On every channel above, a ready checkout then answers requires_escalation with continue_url, the link to that page.
Blocked / exception
Shopify checkout needs a connected store; Plural needs saved credentials with a webhook secret. Without a method, buyers get no payment link.

See Getting paid for what the buyer sees, the Orders page and the email for each order.

Phase 5. Agent-executed payment: off until a sandbox run passes

Agent-executed payment, where AgenticOrg charges through a payment provider against verified buyer mandates, stays off. It is turned on only after a full run against the payment provider's sandbox has passed in staging, and then one merchant at a time. A shop that chose where buyers pay always hands the buyer a link instead. A shop with neither gives no payment link, its checkouts stop before payment, and no buyer is charged.

Grantex mandatesOwner: Platform operator and merchant
The operator turns on mandates and you name your Grantex commerce tenant and merchant in your settings.
Blocked / exception
Without mandates, production refuses agent-executed decisions as buyer_authority_verified.
Sandbox credentialsOwner: Platform operator
The operator stores the provider's sandbox credentials in the secret manager.
Blocked / exception
Without credentials the sandbox tests are skipped, not passed.
Staging runOwner: Platform operator
In staging, turn on payment execution for one test merchant and run the sandbox tests and the checkout smoke test.
Blocked / exception
Any failure keeps payments off.
Check the ledgerOwner: Platform operator
Confirm each payment call comes after a consumed allow decision.
Blocked / exception
A payment row without a consumed decision is an irregularity; stop and investigate.
Production, one merchant at a timeOwner: Platform operator
After owner approval, name the executor for one merchant whose payment method is off, and watch its first orders. A shop with a payment method keeps getting links.
Blocked / exception
Remove the merchant's executor setting to stop it at once.

Mandates matter only for agent-executed payment. A payment link needs none: the buyer authenticates and pays on your own page.

Quick test before you go live

Ask a buyer question and check the source and freshness label.
Open a test checkout and confirm it reaches ready_for_complete.
Complete it and confirm the answer is requires_escalation with a continue_url to your payment page. With Plural in Sandbox, pay the link and check the order on the Orders page and the email.
Export the ledger and run scripts/verify_ledger.py on it.

Sell everywhere
Getting paid
Feature switches reference
Commerce runtime and Shopify
Technical references: UCP profile, ACP feed and sessions, payment hand-off and the launch and rollback runbook