Advanced GraphQL API Usage in Crystallize

In Crystallize, each item (product, document, or folder) uses components to store item data. The components can be as simple as a single line or numeric to more complex structural components like chunks, choices, and pieces. These components can then be placed inside the structural components, which makes it a very powerful system for content modeling.

The level of complexity increases with every level of nesting we add, and often, it is very difficult to update a single component that is nested in a few levels. To solve this problem, we use the CORE API with the `updateComponent` mutation where the `componentId` is constructed by the parent componentId-s separated by `/`. 

Endpoint: api.crystallize.com/@fyour-tenant-identifier

mutation {
  updateComponent(
    itemId: "66b1c6fab4ddfae18c2ee0c0"
    language: "en"
    component: {componentId: "meta/title", singleLine: {text: "Hello World"}}
  ) {
    ... on UpdatedComponent {
      updatedComponentPath
    }
  }
}

Every e-shop requires good searching and filtering capabilities to help its users find what they need quickly. Here is an example of using Discover API to combine multiple filters using logical operators and even filtering on item component data.

Additionally, faceting can be set to narrow down and fine-tune the search results. Here (really), the sky's the limit, so I’d recommend reading the documentation and building your query to match your needs.

Endpoint: api.crystallize.com/your-tenant-identifier/discovery

query SearchProductsSorting {
  search(
    term: "chair", 
    options: {fuzzy: {fuzziness: DOUBLE}},
    filters: {shape: {in: ["product"] } }
    sorting: {variants_name:asc, price_default:desc }
  )
  {
    hits {
      ... on product {
        name
        variants{
          name
          price:defaultPrice
        }
      }
    }
  }
}

We released the Shop API to tackle the challenge of managing the cart functionality of your e-commerce store. The Shop API handles everything, including your cart, cart-related calculations, any promotions you want to set, and much more.

Let’s look at how you can hydrate a cart with items from your Crystallize tenant and an external item. For items in Crystallize, It is as easy as providing the SKU and the quantity.

Endpoint: shop-api.crystallize.com/your-tenant-identifier/cart

mutation {
  hydrate(input: {
    items:[
      { 
      	sku: "robot-pink-standard",
        quantity: 1
      },
    ]
      externalItems: [
      {
         sku:"my-shipping-cost-sku"
         quantity: 1
         name:"Shipping with Fedex"
	    variant: {
           price: {
              gross: 120
              net:100
           }
         product : {
            id:"my-shipping-product-id"
            path:"an url"
         }
       }
     }
   ]
}) {
    ...dataThatYouWant
  }
}

You also get access to our Subscription engine, which has its own API to handle creating and renewing subscriptions. It also includes the ability to track subscription usage for metric-based subscriptions.

Let’s first see how you can create a subscription contract for a customer. Please note that you need a Subscription plan to create a contract.

Endpoint: api.crystallize.com/your-tenant-identifier/subscriptions

mutation CREATE_SUBSCRIPTION_CONTRACT {
  subscriptionContracts {
    create(input: {
      tenantId: "TENANT_ID"
      subscriptionPlan: {
        identifier: "PLAN_IDENTIFIER"
        periodId: "PERIOD_ID"
      }
      customerIdentifier: "legolasgreenleaf@fellowship.com"
      item: {
        name: "ITEM_NAME"
        sku: "ITEM_SKU"
      }
      recurring: {
        price: 10.00
        currency: "EUR"
      }
      status: {
        activeUntil: "2045-12-25T00:00:00"
        renewAt: "2024-10-14T00:00:00"
        price: 10.00
        currency: "EUR"
      }
    }){
      id
    }
  }
}

Once a Subscription contract is created, this is how you would fetch the usage.

query {
  subscriptionContracts {
    get(id: "subscription-contract-id") {
      usage(start: "2019-12-01T10:00:00Z", end: "2020-12-01T10:00:00Z") {
        meteredVariableId
        quantity
      }
    }
  }
}

Based on the contract period, you would most likely have renewal events in place. The mutation just requires you to pass the contract ID:

mutation RENEW_SUBSCRIPTION_CONTRACT {
  subscriptionContracts {
    renew(id: "CONTRACT_ID"){
      id
    }
  }
}

Order management in Crystallize can start by creating an order and then going further to manage it via a pipeline. The whole process requires accessing multiple APIs. The creation of an order is done via the Orders API. One thing to remember here is that the Orders API returns precisely what you provide. It will do nothing behind the scenes. The order creation mutation takes information about the cart and the customer.

Endpoint: api.crystallize.com/your-tenant-identifier/orders

mutation CREATE_ORDER {
  orders {
    create(
      input: {
        customer: {
          firstName: "Legolas"
          lastName: "Greenleaf"
          identifier: "legolasgreenleaf@fellowship.com"
          addresses: [
            {
              type: billing
              streetNumber: "16"
              street: "Greenwood"
              city: "Woodland Realm"
              country: "Ithilien"
              postalCode: "9999"
              email: "legolasgreenleaf@fellowship.com"
            }
          ]
        }
        cart: {
          name: "Bow of the Galadhrim"
          sku: "bow-galadhrim"
          imageUrl: "https://media.crystallize.com/lotr/23/1/27/6/@200/bow-galadhrim.avif"
          quantity: 1
          price: {
            gross: 1000
            net: 800
            tax: { name: "Tax", percent: 25 }
            currency: "EUR"
          }
        }
        payment: {
          provider: custom
          custom: {
            properties: { property: "payment_method", value: "Invoice" }
          }
        }
        total: {
          gross: 1000
          net: 800
          currency: "EUR"
          tax: { name: "Tax", percent: 25 }
        }
      }
    ) {
      id
    }
  }
}

Once an order is created, you might want to place it in a pipeline. You can configure a webhook to fire off on order creation, which can trigger the pipeline stage change mutation via the PIM API.

mutation SET_PIPELINE_STAGE {
  order {
    setPipelineStage(
      orderId: "ORDER_ID"
      pipelineId: "PIPELINE_ID"
      stageId: "STAGE_ID"
    ) {
      id
    }
  }
}

You can further edit or delete an order using the same API or fetch orders based on some filtering via either the PIM API or our new shiny Core API, which has more filters.