The Customei API is currently in developer preview. The overall shape is stable, but individual queries and mutations may change before general availability. We’ll publish a changelog as things move.
- A two-way integration — not just “tell me when an order arrives” (that’s webhooks) but “let me programmatically create templates, update option sets, or read personalization data”.
- Scripted admin automation — bulk-create products, sync libraries from an external asset pipeline, export orders nightly.
- A custom admin UI — build your own dashboard that reads from the same data your Customei admin sees.
Base URL and endpoint
All GraphQL requests go to a single endpoint:<your-app-host> is the URL Customei is served from for your store — in production that’s the Customei-managed host where your embedded admin runs. The same host accepts both GET and POST requests against /api/graphql, though you’ll almost always use POST with a JSON body.
What you can do
| Area | What’s available |
|---|---|
| Templates | Read, create, update, soft-delete, duplicate design templates and their layers. |
| Option sets | Read, create, update, delete option sets and their fields, values, and bindings. |
| Libraries | Read and manage clipart, fonts, and reusable assets. |
| Products | Read shop products, assign/unassign a template + option set to each. |
| Orders | Read order line items, personalization payloads, and print-file status. Trigger a regeneration of a print file. |
| Translations | Read and upsert option-set translations, run glossary lookups. |
| Webhooks | Create, list, update, and delete webhook subscriptions (same surface as the admin UI). |
| Jobs and events | Query background-job status; subscribe to real-time events via Server-Sent Events. |
/api/graphql in your browser (authenticated sessions get the interactive explorer).
Authentication in one sentence
Requests must carry a valid Shopify session token for the shop whose account you’re accessing. The token is extracted from your App Bridge embedded context in production, or supplied via env vars during local development. Full details in Authentication.Multi-tenancy: account vs shop
The API always scopes to an account — the top-level owner of templates, option sets, and libraries — and a shop — the specific Shopify store you’re operating on. Both are derived from your session token automatically, so you don’t have to passaccountId or shopId on every request. You just issue queries and the context ensures you only see your own data.
If you’re building tooling that operates across multiple shops under the same account, issue requests from each shop’s session token — Customei routes each call to the right shop-scoped subset of data.
Relationship to webhooks
The API and webhooks are complementary:- Webhooks push events to you (order.created, order.paid, etc.). You react.
- API lets you pull data or make changes on demand. You initiate.
Rate limits
Customei enforces per-account rate limits on the API. See Errors and rate limits for the specific caps, how they’re signaled, and the best way to back off.Permissions
Every query and mutation runs as the current member, respecting their role and permission overrides. For example, a Staff member can runtemplates queries by default but calling deleteTemplate will fail unless they have template:delete granted explicitly.
When you build a tool that calls the API, make sure the member whose token it’s using actually has the permissions the tool needs.
Next
- Authentication — how to get and send a session token.
- GraphQL quickstart — your first query, end to end.
- App proxy endpoints — the public, storefront-facing endpoints.
- Errors and rate limits — failure modes and retry guidance.