Skip to main content

Standard API

The Standard API provides core functionality available to all admin UI extension types. Use this API to authenticate with your app backend, query the GraphQL Admin API, translate content, handle navigation intents, and persist data in browser storage.

Anchor to Use casesUse cases

  • GraphQL queries: Query the GraphQL Admin API to fetch product, order, or customer data.
  • Internationalization: Display translated content in the merchant's preferred language.
  • Admin navigation: Navigate programmatically to other admin pages or resource details.
  • Intent handling: Handle navigation requests from other extensions to open your action modals.
Support
Targets (1)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides core properties available to all extension targets. Access the following properties on shopify to authenticate users, query the GraphQL Admin API, translate content, handle intents, and persist data.

Anchor to auth
auth
required

Provides methods for authenticating calls to your app backend. Use the idToken() method to retrieve a signed JWT token that verifies the current user's identity for secure server-side operations.

Anchor to extension
extension
{ target: ; }
required

The identifier of the running extension target. Use this to determine which target your extension is rendering in and conditionally adjust functionality or UI based on the extension context.

Anchor to i18n
i18n
required

Utilities for translating content according to the current localization of the admin. Use these methods to provide translated strings that match the merchant's language preferences, ensuring your extension is accessible to a global audience.

Anchor to intents
intents
required

Provides information to the receiver of an intent. Use this to access data passed from other extensions or parts of the admin when your extension is launched through intent-based navigation.

Anchor to query
query
< = unknown, Variables = { [key: string]: unknown; }>(query: string, options?: { variables?: Variables; version?: Omit<, "2023-04">; }) => Promise<{ data?: ; errors?: []; }>
required

Executes GraphQL queries against the GraphQL Admin API. Use this to fetch shop data, manage resources, or perform mutations. Queries are automatically authenticated with the current user's permissions. Optionally specify GraphQL variables and API version for your query.

Anchor to storage
storage
required

Provides methods for persisting data in browser storage that is scoped to your extension. Use this to store user preferences, cache data, maintain state across sessions, or save temporary working data. Storage is persistent across page reloads and isolated per extension.

Anchor to Best practicesBest practices

  • Handle GraphQL partial data: Check both errors and data in query responses. GraphQL returns partial data with errors when some fields fail but others succeed.
  • Catch StorageExceededError exceptions: storage.set() and storage.setMany() throw StorageExceededError when you exceed storage limits. Catch these errors and handle quota failures gracefully.
  • Use storage.setMany() for batch updates: When updating multiple related values, use setMany() with an array of entries for efficient batch operations.
  • Batch GraphQL queries: Combine multiple queries in a single GraphQL request using aliases to reduce roundtrips and improve performance under rate limits.

Anchor to LimitationsLimitations

  • Storage is scoped per extension. Data saved by one extension is inaccessible to other extensions, even from the same app.
  • Storage values are serialized with JSON.stringify, so functions, symbols, and circular references aren't supported.
  • GraphQL queries share rate limits with your app's overall Admin API usage and are subject to the shop's installed access scopes.
  • ID tokens from auth.idToken() are short-lived JWTs. Call auth.idToken() on each request instead of caching tokens.
Was this page helpful?