Developer docs
Build on Tanqory
Guides to the Admin, Store and AI APIs: how to sign in, which host to call, and how errors, limits, paging and versions work. Every guide is checked against the API reference.
# First, sign in on the Admin API for a tokencurl https://api.tanqory.com/v1/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "sofia@example.com", "password": "your-password" }'# Then list the stores you can work oncurl https://api.tanqory.com/v1/stores \ -H "Authorization: Bearer $TANQORY_TOKEN"# Last, call the Store API for your store, on the same hostcurl "https://api.tanqory.com/v1/stores/$STORE_ID/collections?limit=20" \ -H "Authorization: Bearer $TANQORY_TOKEN"Get started
From an account to your first call
Three calls: a token from the Admin API, the list of your stores, then your store's data on the same host.
- Getting startedMake your first call: sign in, find your store, read its collections.
| API | Host |
|---|---|
| Admin API | api.tanqory.com |
| Store API | api.tanqory.com |
| AI (MCP) | api.tanqory.com/v1/mcp |
Core concepts
What holds for every call
The three APIs share one token, one error shape and one way to retry, so code you write for one works for the others.
- AuthenticationOne bearer token for the Admin, Store and AI APIs, how to refresh it, store API keys and app tokens.
- Base URLsThe one host per environment that answers every Admin and Store API call, and the AI API host.
- ErrorsOne error object with a stable code, the field at fault and a request ID; each status and what to do.
- Rate limitsWhat a call over a limit gets, and how to retry 429 and 503 with Retry-After and backoff.
- PaginationThe paging styles the reference declares, limit with page, offset or cursor, and which lists use which.
- VersioningThe version is in the path, v1 keeps serving unchanged, and replaced operations are marked deprecated.
{ "error": { "type": "validation_error", "code": "validation_failed", "title": "Please check your input", "message": "Some fields need attention before you can continue.", "status": 400, "param": "email", "errors": [ { "field": "email", "code": "invalid_type", "message": "Required" } ], "request_id": "e7cab0b72a2507b9953f4d1d3afb092f", "instance": "/api/v1/auth/register" }}Theme CLI
Build themes from your terminal
Scaffold from Nova, run on localhost with your dev store data, then push and submit.
- Get started with the CLIInstall the CLI, sign in, scaffold a theme from Nova, run it on localhost and push it to your dev store.
- CLI authenticationSign the CLI in through your browser or with a tqd_ token, and use TANQORY_TOKEN in CI.
- CLI commandsEvery tanqory theme command and flag in @tanqory/cli 0.9.0, plus the files and variables it reads.
- Theme anatomyThe folders of a Nova based theme, how a section is defined and how templates compose pages.
- Code and the visual editorHow local code and the visual editor share one store theme, and how live-sync keeps them in step.
- Work with existing themesContinue a theme from your dev store, push a folder you already have, or start again from Nova.
npm install -g @tanqory/clitanqory logintanqory theme init my-themecd my-theme && pnpm installtanqory theme devThemes
Themes are React apps
Sections are React components, pages are JSON templates, data comes through typed hooks.
- Themes overviewTanqory themes are React apps: sections, JSON templates, typed data hooks and helper functions.
- ObjectsEverything a theme can read through useData() and useCart(): store, content, catalog, cart and customer.
- HelpersThe helper functions that replace template filters: money, dates, weight, images and translation.
export default defineSection({ name: 'promo', title: 'Promo', attributes: { heading: { type: 'text', label: 'Heading' }, }, component: Promo,})Apps
Build an app merchants install
You host the app and Tanqory frames it in the dashboard, scoped to the permissions each merchant grants.
- App quickstartInstall the CLI, scaffold an app and see it framed inside a development store with tanqory app dev.
- Manual app setupRegister an app, write tanqory.app.json, build the embedded page and webhook handler, and test install by hand.
- App authenticationThe three credentials an app uses: client ID and secret, a store access token, and the embedded session.
- App permissionsScopes in domain.action form from a closed catalog: the 14 domains, how review reads them, and PENDING_REAUTH.
- App CLI commandsEvery tanqory app command in @tanqory/cli: init, dev, deploy, withdraw and info, their options and the files they write.
- App notificationsAdd an SMS or email channel or take over a notification type: provides, dispatchUrl, the dispatch body and status reports.
- AI coding assistantsThe AGENTS.md and CLAUDE.md every new app ships with, what they tell an assistant, and how to check it reads them.
- Submit an app for reviewWhat a version pins, the reason every scope needs, the three preflight checks, and the app, version and install states.
- Publish an appAfter approval: the listing merchants see, consent per install, rotating the secret and the per-install delivery log.
npm install -g @tanqory/clitanqory logintanqory app init order-notifiercd order-notifiertanqory app dev --openWebhooks
Every event a store sends
Signed POSTs to your endpoint when something happens in a store, one topic per resource and action.
- Webhook event catalogEvery live webhook topic, 82 in 23 resources, who can subscribe, the delivery headers and the payload envelope.
{ "webhooks": [ { "topic": "orders/create", "path": "/hooks/orders" }, { "topic": "app/uninstalled", "path": "/hooks/uninstalled" } ]}Reference
Every operation, every library
When a guide is not enough, the reference documents each operation from the OpenAPI documents, and the libraries page lists the packages and templates.
- API referenceEvery published operation of the Admin, Store and AI APIs, with parameters and answers.
- Store webhooksThe events a store sends, how to subscribe and how to check the signature.
- API policyThe version each API carries, deprecated operations and the 429 answer.
- Libraries and templatesThe app template, the plugin SDK, App Bridge and the CLI.
- ThemesBuild store themes in React and TypeScript with the CLI.