GraphQL Admin API
Manage your CloudCart store programmatically with the GraphQL Admin API.
The GraphQL Admin API gives you full access to your CloudCart store — products, orders, customers, discounts, marketing, settings. One endpoint, everything the admin panel can do.
Endpoint & auth
POST /api/gql HTTP/1.1
Host: {shop}.cloudcart.com
Authorization: Bearer cc_pat_xxxxxxxxxxxxx
Content-Type: application/jsonAuthenticate with a Personal Access Token (cc_pat_…), created in Settings → PAT Tokens. Start with Read Only, scope up when you need writes.
30-second test
curl -X POST https://mystore.cloudcart.com/api/gql \
-H "Authorization: Bearer $CLOUDCART_PAT" \
-H "Content-Type: application/json" \
-d '{"query": "{ generalSettings { siteName } }"}'The three rules that prevent 90% of errors
- Output is
camelCase, grouped into sub-objects.Product.pricing { from to },Product.flags { active },Order.amounts { total },Order.buyer. Flat fields likeproduct.pricedon't exist. - Arguments and inputs are
snake_case.category_id,price_min,url_handle. - Lists are connections.
products(first: 10) { edges { node { … } } pageInfo { total } }— see Pagination.
query {
products(first: 10) {
edges {
node {
id
name
pricing { from to }
flags { active }
}
}
pageInfo { total }
}
}What you can work with
| Area | Read | Write | Notes |
|---|---|---|---|
| Products | product(id:), products(…), productSearch(query:) | createProduct, updateProduct, deleteProduct | Rich filters: query, sku, active, category_id, price_min/max, stock |
| Product content | product tabs, files, labels, banners, reviews, questions | createProductTab, createProductFile, createProductLabel, … | |
| Orders | orders(…) with admin-grade filters | fulfillment, status mutations | Order.amounts, Order.buyer, Order.statuses sub-objects |
| Customers | customers(…) incl. total_spent, segment filters | create / update mutations | |
| Discounts & codes | discounts, codes | create / update / delete | |
| Segments | segmentConditions, segment queries | createSegment | Condition tree discovered via segmentConditions first |
| Bulk operations | bulkOperationStatus(jobId) | productsBulkAdjustPrice, productsBulkApplyDiscount, productsBulkRoundPrices, … | Async, queue-backed — the only safe way past a few dozen records |
| Apps & integrations | application(key:), applications(…) | app-specific mutations | Shipping, payments, ERP/POS ship as marketplace apps — check isInstalled / isActive / isConfigured first |
| Settings | generalSettings, … | update mutations | |
| CLI tokens | cliTokens | createCliToken, updateCliToken | Manage PATs programmatically |
This is a map, not an inventory — the schema is large. Discover precisely what you need:
# Search the live schema by topic
cloudcart app schema --search segment --compact
# Or let your AI assistant do it via the MCP serverLet your AI assistant write the queries
The Dev MCP server gives Claude Code, Cursor, Codex CLI, and Gemini CLI direct access to this schema — semantic search in any language, plus validation of every query before you run it. Pair it with the CloudCart CLI to execute.
Guides
- Queries — single resources, lists, filters, variables
- Mutations — create/update/delete, snake_case inputs, bulk operations
- Pagination — cursors,
pageInfo, full-walk pattern - Error Handling — error shape, validation errors, retries
- Webhooks — event notifications with HMAC signatures
- CSV Import / XML Import — bulk data import