Merchant API
A store-scoped HTTP interface for reading catalog, stock, orders, reports, coupons, support conversations, reviews, and custom-order requests, and for making the changes the token's write scopes allow.
Built
Shop Bot / merchant integration
Connect to one managed store, with that store's authority.
A managed Shop Bot store exposes its own merchant API and MCP endpoint. Store owners create scoped tokens in Telegram; the store enforces what each token may read or change.
At a glance
- Who it is for
- The owner and operators of a managed Shop Bot store, and developers working for that store.
- What it connects
- Software through the merchant API or Shop SDK; an AI assistant through the store's MCP endpoint or Shop agent plugin.
- Authority
- One token, one store, named scopes. The store keeps confirmations, Telegram approvals, limits, and audit underneath every caller.
- Where it stands
- Built
- Live access
- Check Shop Bot's current public status
Store interfaces
Four ways into the same store policy.
The API and MCP endpoint belong to the individual store. They are not an ApexAPI or ApexMCP gateway, and the SDK and plugin add no product authority of their own.
MCP endpoint
The same store's tools for an AI assistant. The store lists only tools the token may use and enforces every scope, confirmation, approval, and limit.
Built
Shop SDK
The public Python client for the merchant API, with synchronous and asynchronous clients, typed results, pagination, retries, and idempotency keys for changes.
Built
Shop agent plugin
The public Claude Code plugin: skills and a connection to the store's MCP endpoint. It contains no store logic and grants no authority beyond the token.
Built
Create a token
The store owner grants access in Telegram.
Only the store owner creates a token. The bot shows the credential once, beside the address it belongs to.
Start with the owner
Open a private chat with the managed store's bot as its owner.
Open the token menu
Send /apitoken and choose New token.
Set its authority
Choose a preset or custom scopes, name the token, and set its expiry.
Copy once
Copy the token and the store address when the bot shows them. The token is shown once and is bound to one store.
Token presets
Start with the smallest useful scope set.
The bot offers four presets. Custom scopes are available when none matches the job exactly.
Read-only
Read sales, catalog, stock, orders, payments, coupons, reviews, and custom-order requests. It changes nothing.
Support
Read the catalog and orders, reply to and close support conversations, and restore an order's downloads. It has no buyer ids, coupon changes, or catalog changes.
Catalog and stock
Read-only access plus catalog, pricing, membership, product-version, and license-key stock changes.
Full
Every scope, including buyer ids, coupon changes, broadcasts, review moderation, and custom-order questions and rejections.
Changes and approvals
The store decides when a call may take effect.
A caller never promotes a pending or previewed change to completed. The store returns the next required step.
Direct
Routine changes complete in one call when the token has the required scope.
Two-step confirmation
A destructive change first returns a preview of its effect. Nothing changes until the caller presents the single-use confirmation after a person agrees.
Telegram approval
A consequential change returns pending approval and waits for the store owner's Approve in Telegram. Until then it is not done.
Refund boundary
Refunds are never available through the API, MCP endpoint, SDK, or plugin. They stay with the store's operators in Telegram.
Store address
Every token stays with the store that issued it.
The domain is not public yet. The bot supplies the exact address when the owner creates a token; do not construct one from this placeholder.
Address shape
https://<store>.<fleet>.<store domain>/api/merchant/v1
The MCP endpoint is under that store's merchant interface. Use the exact API or MCP address the bot shows.