plugins
Crystallize Plugins
A Crystallize Plugin is a vendor-hosted application that extends the Crystallize App UI inside iframes at predefined placement points. Plugins do not run code in the App UI itself — they receive a scoped Backend Token to act on behalf of the signed-in user via Crystallize APIs, and any secrets they need are encrypted client-side with the vendor's own public key.
The full normative contract — entities, fields, JWE/JWT specs, request shapes, sequence diagrams — lives in references/plugin-contract.md. This SKILL.md is the builder's guide: how to ship a plugin end-to-end. Read the contract when a field, security guarantee, or wire format is in question.
Consultation Approach
Before writing code, get the lay of the land:
- What does the plugin do? Pure UI widget, server-side action on a Crystallize entity (order, customer…), or tenant-wide dashboard? This drives the entrypoint placements.
- Does it need to call Crystallize APIs? If yes, you'll use the
backendTokenfrom the decrypted payload as aBearercredential. - Does it need secrets? API keys, webhook URLs, third-party credentials — these go in
secrets[]and are encrypted in the installer's browser. Crystallize never sees plaintext. - Where does it run? Plugins are server-hosted (Cloudflare Worker, Vercel/Netlify edge, Lambda, plain Node/Bun server). Pure static hosting is not sufficient — the upstream must accept POST requests and decrypt JWE payloads.
- Which tenant(s)? Plugins are installed per-tenant. One plugin can be installed on many tenants, each with its own configuration.
Architecture in 30 Seconds
Three entities (full detail in the contract):
More from crystallizeapi/ai
pricing
Design and implement pricing strategies in Crystallize using Price Variants, Price Lists, Promotions, and Markets. Use when recommending pricing structures, setting up multi-currency support, configuring B2B/B2C pricing, planning promotional campaigns, defining markets, or advising on pricing architecture for commerce projects. Also use when the user asks about currencies, multi-market setup, was/now pricing, strikethrough prices, wholesale pricing, coupon codes, discount campaigns, tiered pricing, cart discounts, tax-inclusive/exclusive pricing, or any question about how prices work in Crystallize — even if they don't explicitly mention "pricing".
15mutation
Mutate data in Crystallize - create products, documents, and folders, update item components, manage product variants and SKUs, publish/unpublish items, handle customers and orders, manage carts and checkout flows, convert cart to order, create orders from checkout or directly (POS, imports), record payments, track fulfillment pipeline stages, upload images and media, import data, delete items, and perform bulk operations. Use this skill when creating or updating any content in Crystallize, adding products to the catalogue, modifying descriptions or fields, setting up checkout, placing orders, managing stock, recording payments, tracking order fulfillment, or writing data through the Core API or Shop API.
13query
Query Crystallize APIs for product data, content, and commerce information. Use this skill when fetching product catalogs, listing items, searching products, filtering by attributes, browsing categories, building storefronts, retrieving cart data, reading orders or customers, building admin dashboards, getting item details by path or ID, implementing faceted navigation, paginating results, or reading any data from Crystallize. Covers Core API, Discovery API, Catalogue API, and Shop API queries. Also use when the user asks about GraphQL queries against Crystallize, reading product variants, getting component data, checking stock levels, or any read operation — even if they don't explicitly say "query".
13content-model
Design content models in Crystallize using Shapes, Pieces, Components, Topic Maps, and Grids. Create product structures, define document types, build taxonomies, organize catalogue items, design relationships between items, implement classification bridges, configure item relations with shape restrictions, and architect scalable data models. Use when modeling content, creating shapes, defining components, building taxonomies, designing relationship patterns, implementing semantic bridges, configuring product variants, or structuring catalogue hierarchies.
13information-architecture
Design folder hierarchies and navigation structures in Crystallize. Create category trees, organize products and content, plan URL structures, and build scalable information architectures. Use when designing storefront navigation, category pages, collection structures, content organization, mega menus, or site maps. Also use when the user mentions organizing their catalog, planning their store structure, restructuring navigation, or asks how to organize products or content in Crystallize — even if they don't explicitly say "information architecture.
13js-api-client
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.
12