Crystallize Mutation Skill

Create, update, and manage data in Crystallize using GraphQL mutations. This skill covers all write operations across the Core API (admin/content management) and Shop API (cart/checkout).

Consultation Approach

Before writing mutations, understand the context. Ask clarifying questions:

1. What are you trying to create or update? Products, documents, folders, customers, orders?
2. Do you have the tenant identifier and access tokens? Mutations require authentication.
3. Where in the flow are you? Content/catalog management → Core API. Cart/checkout/orders → Shop API.
4. Do you need to update individual fields or create items from scratch? updateComponent for fields, create for new items.
5. Should changes be published immediately? Creating an item doesn't publish it — that's a separate step.
6. Are you doing a one-off change or a bulk import? Single mutations vs mass operations.

Decision Tree

What do you need to do?
│
├─ Create/update catalogue items (products, documents, folders)
│  ├─ Create new item → Core API: product/document/folder.create
│  ├─ Update a field on an item → Core API: item.updateComponent
│  ├─ Add/update product variants → Core API: product.setVariants
│  ├─ Publish/unpublish → Core API: item.publish / item.unpublish
│  └─ Delete an item → Core API: item.delete
│
├─ Manage customers
│  ├─ Create individual → Core API: customer.createIndividual
│  ├─ Create organization → Core API: customer.createOrganization
│  └─ Update customer → Core API: customer.update
│
├─ Manage orders
│  ├─ Create order from cart → Shop API /order: createFromCart
│  ├─ Create order directly (POS, import) → Shop API /order: create
│  ├─ Add/update payments → Shop API /order: addPayments / setPayments
│  ├─ Track order through pipeline → Shop API /order: addToStage
│  └─ Update order metadata → Shop API /order: setMeta (or Core API: order.update)
│
├─ Cart & checkout (storefront)
│  ├─ Create/hydrate a cart → Shop API: hydrate
│  ├─ Modify cart items → Shop API: addItems / removeItems / setCartItem
│  ├─ Set customer & addresses → Shop API: setCustomer / setAddresses
│  └─ Convert cart to order → Shop API: cartAsOrderIntent
│
└─ Bulk operations
   └─ Use mass operation JSON via the content-model skill's output format

API Selection

Use Case	API	Why
Creating/editing items, shapes, customers	Core API	Full read/write, admin-level access
Cart management, checkout	Shop API /cart	Edge-distributed cart lifecycle
Order creation, payments, pipelines	Shop API /order	Full order CRUD after checkout
Bulk shape + item creation	Core API via mass operations	Ordered multi-step creation

API Endpoints & Authentication

API	Endpoint	Auth Required	Use For
Core	https://api.crystallize.com/@{tenant}	Yes	Items, shapes, customers
Shop /cart	https://shop-api.crystallize.com/{tenant}/cart	Yes (JWT)	Cart management, checkout
Shop /order	https://shop-api.crystallize.com/{tenant}/order	Yes (JWT)	Order CRUD, payments

Core API

POST https://api.crystallize.com/@{tenant-identifier}

Note the @ prefix before the tenant identifier.

curl -X POST 'https://api.crystallize.com/@your-tenant' \
  -H 'Content-Type: application/json' \
  -H 'X-Crystallize-Access-Token-Id: YOUR_TOKEN_ID' \
  -H 'X-Crystallize-Access-Token-Secret: YOUR_TOKEN_SECRET' \
  -d '{"query": "mutation { ... }"}'

Generate access tokens in the Crystallize App under Settings > Access Tokens. See the permissions skill for scoping tokens.

Shop API

POST https://shop-api.crystallize.com/{tenant-identifier}/cart
Authorization: Bearer YOUR_JWT_TOKEN

No @ prefix for the Shop API endpoint.

Common Workflow Patterns

Create a product end-to-end

1. Create the product with shape and parent folder
2. Set variants with SKU, pricing, stock, and images
3. Update components (description, specs, media)
4. Publish the item

See Core API Reference for each mutation.

Update content on an existing item

1. Query the item to confirm its ID and current state (use the query skill)
2. Call item.updateComponent for each field you need to change
3. Publish if the item should go live immediately

Each updateComponent call targets a single component by componentId. You can update multiple components by sending multiple mutations.

Checkout flow (storefront)

1. Hydrate a cart with product SKUs and quantities
2. Add/remove items as the customer shops
3. Set customer info and addresses
4. Place the cart to lock it for payment
5. Create the order from the placed cart

See Shop API Cart Mutations for steps 1-4, and Shop API Order Mutations for step 5.

Bulk import / mass operations

For creating many items at once, use the mass operations JSON format produced by the content-model skill. Mass operations follow a 4-phase ordering:

1. Pieces (dependencies first)
2. Shapes
3. Topic maps
4. Items

Error Handling

The Core API uses union return types. Always include error fragments in your mutations:

mutation {
  product {
    create(input: { ... }) {
      ... on Product {
        id
        name
      }
      ... on BasicError {
        errorName
        message
      }
    }
  }
}

Common error types: BasicError, UnauthorizedError, ItemNotFoundError, OrderDoesNotBelongToTenantError.

Using the JS API Client

For JavaScript/TypeScript projects, use @crystallize/js-api-client instead of raw HTTP calls. It provides typed helpers for all mutations. See the js-api-client skill for setup and usage.

import { createClient } from "@crystallize/js-api-client";
const api = createClient({
    tenantIdentifier: "your-tenant",
    accessTokenId: "...",
    accessTokenSecret: "...",
});

// Use pimApi for Core API mutations
const result = await api.pimApi(mutationString, variables);

Output Format

When generating mutations for the user, produce:

1. GraphQL mutations with clear variable placeholders (e.g., "your-tenant-id", "item-id")
2. Variable definitions when the mutation uses GraphQL variables
3. Expected response shape so the user knows what to look for

If the user is working in a JS/TS project, prefer generating code using @crystallize/js-api-client helpers.

References

• Core API Mutations - Item CRUD, variants, components, customers, publish/unpublish, delete, media uploads
• Shop API Cart Mutations - Cart hydration, item management, checkout flow, cart lifecycle
• Shop API Order Mutations - Order creation (from cart or direct), payments, pipelines, metadata