Skip to main content

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:
The route accepts Weaverse token types 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.
A successful token lookup proves neither the expected shop nor the scope required by a specific GraphQL field. Read the shop identity and installed scopes before planning a mutation.

Protect the Key

Keep WEAVERSE_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.
Do not include the key in a URL. The proxy accepts it only through the Authorization header.

Verify Shop and Installed Scopes

Make this harmless read before other operations:
Confirm that the returned shop is the intended target and that accessScopes contains the minimum scope required by the proposed operation. Re-read after a merchant changes scopes.

Request Format

Send JSON with a required query 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’s currentAppInstallation.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.
Do not claim that Shopify Markets country/language/currency settings or Customer Account post-logout URIs are mutable through this proxy until the exact current Shopify Admin GraphQL operation has been schema-verified. If no verified operation exists, stop and hand the step to an authorized Shopify Admin operator.

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 and 429 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.