From use-crystallize
Use the @crystallize/js-api-client package to interact with Crystallize APIs in JavaScript/TypeScript. Use when setting up the Crystallize API client, configuring credentials, calling catalogueApi/discoveryApi/pimApi/shopCartApi, working with high-level helpers for catalogue fetching, cart management, orders, customers, subscriptions, navigation, or using any helper from the @crystallize/js-api-client npm package.
How this skill is triggered — by the user, by Claude, or both
Slash command
/use-crystallize:js-api-clientThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
The `@crystallize/js-api-client` package provides typed utilities for working with all Crystallize APIs in JavaScript/TypeScript environments.
The @crystallize/js-api-client package provides typed utilities for working with all Crystallize APIs in JavaScript/TypeScript environments.
Before writing code, understand the context. Ask clarifying questions:
staticAuthToken is enough for read-only. PIM/Shop operations need accessTokenId + accessTokenSecret.pnpm add @crystallize/js-api-client
# or npm install @crystallize/js-api-client
# or yarn add @crystallize/js-api-client
import { createClient } from "@crystallize/js-api-client";
const api = createClient({
tenantIdentifier: "your-tenant",
// For protected APIs, provide credentials:
// accessTokenId: '…',
// accessTokenSecret: '…',
// staticAuthToken: '…', // for read-only catalogue/discovery
});
// Call any GraphQL API with string queries
const { catalogue } = await api.catalogueApi(
`query Q($path: String!, $language: String!) {
catalogue(path: $path, language: $language) {
name
path
}
}`,
{ path: "/shop", language: "en" },
);
// Close when using HTTP/2 option
api.close();
createClient(configuration, options?)
| Option | Description |
|---|---|
tenantIdentifier | Required. Your tenant name |
tenantId | Optional tenant ID |
accessTokenId / accessTokenSecret | For PIM/Shop operations |
sessionId | Alternative to token-based auth |
staticAuthToken | For read-only catalogue/discovery |
shopApiToken | Auto-fetched if not provided |
shopApiStaging | Use staging Shop API |
origin | Custom host suffix (default: .crystallize.com) |
| Option | Description |
|---|---|
useHttp2 | Enable HTTP/2 transport |
profiling | Profiling callbacks for debugging |
extraHeaders | Extra request headers for all calls |
shopApiToken | Control auto-fetch behavior |
All callers share the same signature:
<T>(query: string, variables?: Record<string, unknown>) => Promise<T>;
| Caller | Purpose |
|---|---|
catalogueApi | Catalogue GraphQL |
discoveryApi | Discovery GraphQL (search/browse) |
pimApi | PIM GraphQL (legacy — prefer nextPimApi) |
nextPimApi | PIM Next GraphQL (scoped to tenant, recommended) |
shopCartApi | Shop Cart GraphQL (token auto-handled) |
Available helpers (see High-Level Helpers Reference for full examples):
| Helper | Import | Purpose |
|---|---|---|
createCatalogueFetcher | @crystallize/js-api-client | Build typed catalogue queries with object syntax |
createNavigationFetcher | @crystallize/js-api-client | Fetch navigation trees by depth |
createProductHydrater | @crystallize/js-api-client | Fetch products/variants by path or SKU |
createOrderFetcher | @crystallize/js-api-client | Fetch orders with type-safe field selection |
createOrderManager | @crystallize/js-api-client | Create/update orders, set payments, move pipeline stages |
createCustomerManager | @crystallize/js-api-client | Create and update customers |
createCustomerGroupManager | @crystallize/js-api-client | Manage customer groups |
createSubscriptionContractManager | @crystallize/js-api-client | Create and manage subscription contracts |
createCartManager | @crystallize/js-api-client | Hydrate carts, add items, place orders (token auto-handled) |
| Auth Type | Use Case |
|---|---|
staticAuthToken | Read-only catalogue/discovery |
accessTokenId + accessTokenSecret | PIM/Shop operations |
sessionId | Alternative to token pair |
shopApiToken | Optional; auto-fetched if omitted |
Generate access tokens in the Crystallize App: Settings → Access Tokens
npx claudepluginhub crystallizeapi/ai --plugin use-crystallizeAdds customer authentication to Shopify shop templates using better-auth with OIDC. Includes login flow, profile, orders, addresses pages, and nav integration.
Executes direct GraphQL queries and mutations on Shopify Storefront API for custom storefront data fetching and cart operations when full UI control is needed, not for web components.
Sets up Shopify CLI auth and Admin API access token for a store: install CLI, login, create custom app with scopes, store token securely, verify with GraphQL. For store connections or auth issues.