Shopify Admin API Proxy
The Admin API Proxy forwards a Shopify Admin GraphQL query or mutation through Weaverse to the Shopify shop associated with the key. Weaverse uses the connected app installation’s OAuth access token; it does not transform or cache the GraphQL response. Use it only from a trusted server for shop-scoped reads or reviewed automation. Never expose the key in browser code.Authentication and Authority
Send a bearer token to:shopify and content_api. It rejects agent_cli and other narrower token types.
A valid key identifies one Weaverse shop. Shopify authority comes from the connected Weaverse app installation’s currently granted Admin API scopes—not from an unrestricted capability on the key. Manage those scopes in Weaverse Dashboard → Settings → Shopify Admin API Proxy → Manage Scopes.
Protect the Key
KeepWEAVERSE_API_KEY in a dedicated, untracked server environment file with owner-only 0600 permissions. Load it through the server runtime. Never print the value or paste it into a prompt, command line, documentation, diff, client bundle, or log.
Authorization header.
Verify Shop and Installed Scopes
Make this harmless read before other operations:accessScopes contains the minimum scope required by the proposed operation. Re-read after a merchant changes scopes.
Request Format
Send JSON with a requiredquery string and optional variables object:
The proxy passes both fields to Shopify as-is. Validate operations against the current Shopify Admin GraphQL schema; proxy access does not prove that a field or mutation exists.
A successful response is Shopify’s
data object directly, not a {data, errors} envelope. The current server client turns top-level GraphQL errors into a thrown, sanitized 500 proxy error. Mutation payload userErrors remain in the returned data and must be checked by the caller.
Scope Management
The Manage Scopes screen reads the active scopes from Shopify’scurrentAppInstallation.accessScopes and starts Shopify’s scope-grant flow when the merchant requests more access.
The installed app marks these scopes as required:
Optional scopes include pairs such as
read_orders/write_orders, read_customers/write_customers, read_inventory/write_inventory, and read_shipping/write_shipping. The Dashboard’s current Manage Scopes list is authoritative.
Request the minimum scope for the exact operation. Adding scopes changes the connected Shopify app installation and requires merchant authorization.
Rate and Timeout Limits
The proxy enforces 1,000 requests per hour per token and a 15-second timeout for each Shopify GraphQL operation. Successful responses and429 Too Many Requests responses include rate-limit headers:
A query that exceeds 15 seconds currently returns the proxy’s sanitized server-error response. Reduce the selection or paginate; do not retry an unchanged expensive query in a tight loop.
Safe Mutation Sequence
1
Inspect current state
Run the identity/scope probe, then read the exact Shopify resource that may change. Keep the original identifiers and values for comparison.
2
Review a minimum mutation
Validate the mutation against the current Shopify schema, confirm its required installed scope, and prepare only the fields that must change. Prefer an idempotent operation whose repeat execution is a no-op after the desired state exists.
3
Approve at the point of risk
Obtain explicit approval immediately before destructive, permission, publication, or other high-impact mutations. A prior read or general request to investigate is not mutation approval.
4
Inspect every error channel
Check the HTTP status and proxy error envelope. The proxy maps top-level GraphQL
errors to a sanitized 500; do not treat that as a retryable success. For a mutation that returns HTTP 200, inspect its operation-specific userErrors before accepting the result.5
Read back exact state
Query the same resource by its stable identifier and compare exact fields with the reviewed target. Only then verify the affected storefront route and behavior.
Error Handling
Storefront Verification
After an approved localization-related change, verify the actual storefront surface: supported and unsupported market routes, Storefront country/language/currency context,<html lang> and dir, localized links and redirects, cart buyer identity, checkout continuity, canonical URLs, hreflang, and sitemap output.
Markets and Localization
Configure the canonical market contract and production checks.
Content API
Read and update shop-scoped Weaverse project content.