Skip to main content
More in Learn

Importing Data into Crystallize

Whether you’re moving to Crystallize from another system, starting from scratch with a great deal of data to add, or copying an existing tenant, Crystallize offers many flexible and time-saving methods for importing data.

Before You Begin

There are many ways to import data into Crystallize, catering to different scenarios:

  • Initial (or recurring) import from an external source that may include:
    • Performing batch editing operations, e.g. adding a whole spreadsheet’s worth of products to your tenant at once.
    • Integrating seamlessly between Crystallize and third-party applications that support file formats like XLS, JSON, CSV, XML, HTML, or Markdown.
    • Manual import/export.
  • Automated import/export for backup, CI/CD, or local development that may include:
    • Duplicating tenants for backup purposes.
    • Creating staging/development environments.

If you’re performing your initial import of data, your first step should always be to build a strong content model. This is to instruct Crystallize how your data will be structured. We offer a content modeling kit along with helpful advice within our Best Practices section. Once you’ve properly established your structure–components, relations, shapes, items, and catalogue–you’re ready to import data.

Requirements and Notes

Import Using the Crystallize CLI

The Crystallize command line interface (CLI) is an open-source application. (You can contribute to the CLI here.) Within the CLI, you can run the following command to create a “spec” file containing the target tenant’s data:

npx @crystallize/cli-next@latest dump ~/my-projects/mydumpfolder tenantIdentifier

The CLI has many options that you can see by using the `--help` flag. For instance, you may want to add `--exclude-orders=false` and `--exclude-customers=false` to include Orders and Customers in the spec file. (This is disabled by default.)

Once you have your spec file, you can import it into a target tenant with the following command:

npx @crystallize/cli-next@latest import ~/my-projects/mydumpfolder/spec.json tenantIdentifier

Please note that if you use the CLI, there’s currently no option to exclude anything to be imported. If there’s anything you don’t want to import, you have two options:

  • Remove it from the spec file (after the dump command and before the import).
  • Use the import-utilities tools instead, which are described below.

Import Using the PIM API Tenant Copy

This method does everything server-side. Currently, it’s available for Crystal plan customers only, but will eventually be open to all activated accounts. (If you have any questions about your Crystallize plan, you can contact our sales team.)

In the PIM API, use the following mutation to trigger the cloning of a tenant:

mutation {
  tenant {
      exclude: assets
      overwrite: true|false
      tenantId: "0987654123123"
    ) {

With this command, you can copy an existing tenant and either create a new tenant with the data, or overwrite an existing tenant that you own by specifying overwrite: true. This method of copying a tenant is the fastest, and it will aggregate usage on the source tenant.

Import Using Import-Utilities

The Crystallize import-utilities are a set of tools that enable powerful import and export operations between Crystallize tenants, data specification, and conversion between a solid range of file formats. As free open-source code, you can use import-utilities in conjunction with the Crystallize APIs you already have and adjust it to support your own unique applications.

Whether you need to perform data dumps, automate backups, or pull data from Crystallize to convert and use somewhere else, you have the flexibility to do pretty much anything. See for yourself the many examples already coded for you at our example repository.

You can also check out our import-utilities livestream for more information:

Import Using Individual Mutations

You could manually import data using the product.create, product.update, and all the other mutations available within the PIM API. This is not recommended for most use cases, as you will miss optimization, throttling, and many things you get out of the box by using import-utilities.

Import with the Crystallize App

The Crystallize App supports Apps, which are custom external applications that you can link to via a URL. Anyone may create and add Apps to their tenant. Crystallize offers a number of open-source Apps as well. One of these is the Crystallize Import App, a user interface to import/export data by doing a field mapping.

Check Out Our Importing and Synchronizing Data Livestream

People showing thumbs up

Need further assistance?

Ask the Crystallize team or other enthusiasts in our slack community.

Join our slack community