Crystallize logo

Customer & order imports

This guide explains how to use Crystallize Mass Operations to import customers and orders at scale. Mass Operations allow you to perform thousands of actions—like creating customers and registering historical orders—using a single declarative JSON file.

You can find the raw JSON examples here:

Customer Import Details

The customer/upsert intent is the most efficient way to import customer data because it is idempotent: it creates the customer if they don't exist and updates them if they do.

Key Fields to Map:

  • identifier: A unique string to identify the customer (usually an email or an ID from your legacy system).
  • type: Either individual or organization.
  • firstName / lastName: The persona details.
  • addresses: An array containing billing and shipping objects.
  • middleName / companyName: Optional metadata.

Example Operation:

{
  "intent": "customer/upsert",
  "identifier": "customer-123",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@example.com",
  "type": "individual",
  "addresses": [
    {
      "type": "billing",
      "street": "123 Commerce St",
      "city": "Oslo",
      "country": "Norway"
    }
  ]
}

Order Import Details

Importing orders usually involves either registering a new order intent or upserting historical order data.

Key Concepts:

  • order/register: Used for active orders where you want Crystallize to handle the standard order logic.
  • order/upsert: Best for migrating legacy data where you need to preserve original IDs and timestamps.
  • Cart Items: Every order must contain a list of items with sku, name, quantity, and price.
  • Customer Reference: You can link an order to a customer using their identifier.

Example Operation:

{
  "intent": "order/upsert",
  "customer": {
    "identifier": "customer-123"
  },
  "cart": [
    {
      "sku": "product-sku-1",
      "name": "Eco-friendly Chair",
      "quantity": 1,
      "price": {
        "gross": 150,
        "net": 120,
        "currency": "EUR"
      }
    }
  ],
  "total": {
    "gross": 150,
    "net": 120,
    "currency": "EUR"
  },
  "payment": [
    {
      "provider": "stripe",
      "stripe": {
        "orderId": "ch_12345"
      }
    }
  ]
}

Advanced: Chaining Imports

One of the most powerful features of Mass Operations is the ability to use _ref. This allows you to create a customer and immediately reference them in an order within the same file.

{
  "version": "0.0.1",
  "operations": [
    {
      "_ref": "newCustomer",
      "intent": "customer/upsert",
      "identifier": "jane-doe-ref",
      "firstName": "Jane"
    },
    {
      "intent": "order/upsert",
      "customer": {
        "identifier": "{{ newCustomer.identifier }}"
      },
      "cart": [...]
    }
  ]
}

Pro Tips for Success

  • Idempotency: Always prefer upsert over create. This allows you to re-run the same file if a network error occurs without creating duplicate records.
  • Validation: Start with a small file (5-10 records) to ensure your field mapping is correct before running thousands.
  • Logs: Check the operationLogs query if a task shows as "Complete with errors" to see exactly which SKU or Customer ID caused the issue.
;