> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stigg.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Import my Zuora catalog into Stigg

Stigg now supports importing existing Zuora product catalogs directly into your Stigg environment. This allows you to adopt Stigg without restructuring your billing setup, while keeping Zuora as the authoritative source of truth for products, plans, and pricing.

With the [Zuora Catalog Import Script](https://github.com/stiggio/import-scripts), you can mirror your Zuora catalog structure in Stigg, manage entitlements on top of it, and keep billing ownership firmly with your finance team.

## What’s new

Many organizations treat Zuora as the rigid source of truth for their product catalog. Recreating this structure manually in a new system can be error-prone and often forces you to duplicate SKUs to support different billing frequencies.

Stigg provides a scripted import tool that solves this by **mirroring your Zuora hierarchy**. It allows you to map multiple Zuora products and rate plans into a unified Stigg catalog without disrupting your downstream reporting or CPQ rules.

## Zuora catalog import script

The Zuora catalog import script imports product catalog data from Zuora into Stigg by converting Zuora products, rate plans, and charges into Stigg products, plans, add-ons, and prices using the Stigg GraphQL API.

### Key features

* Imports Zuora products, plans, add-ons, and flat-rate prices into Stigg
* Automatically detects add-ons based on naming (`add-on` / `addon`)
* Maps multiple Zuora products to the same Stigg product — all rate plans from every listed product are consolidated under one catalog entry
* Supports create, update, and publish workflows
* Grandfathered plan forking — mark a plan or add-on as grandfathered so the next import creates a new copy with entitlements preserved, leaving the original untouched
* Dry-run mode to preview changes without modifying Stigg

### How it works

All Zuora products listed in `ZUORA_PRODUCT_IDS` are consolidated into a single Stigg product. The first product becomes the main product entry; all plans and add-ons from every additional product are assigned to it. Zuora rate plans are split into Stigg plans and add-ons, with add-ons detected automatically based on naming conventions. Only flat-rate and per-unit (imported as flat-fee) pricing models are supported. Packages are grouped by billing period and all imported entities are created as drafts by default.

### Unarchiving existing products and plans

If a product or package with the same `refId` already exists in Stigg and is archived, the script will automatically unarchive it during import rather than creating a duplicate.

## Requirements

To run the Zuora catalog import script, make sure the following prerequisites are installed on your system:

* **Node.js** (required to run the import script)
* **Yarn or npm** (used to install dependencies and execute the script)

## Getting started

### 1. Clone the import Script Repository

Clone the public repository that contains the Zuora-to-Stigg import script:

```bash theme={null}
git clone https://github.com/stiggio/import-scripts
cd import-catalog-from-zuora
```

### 2. Configure environment variables

1. Use the provided `.env.example` file as a template:

   ```bash theme={null}
   cp .env.example .env
   ```

2. Update the following values in `.env`:

   ```bash theme={null}
   X_API_KEY=your-stigg-server-api-key
   ENVIRONMENT_ID=your-stigg-environment-id
   ZUORA_PRODUCT_IDS=zuoraProductId1,zuoraProductId2
   ```

   * `ZUORA_PRODUCT_IDS` accepts a comma-separated list of Zuora product IDs to import.

### 3. Install dependencies

Install the required dependencies using Yarn or npm:

```bash theme={null}
yarn install
```

or

```bash theme={null}
npm install
```

### 4. Preview the import (recommended)

Before making any changes, run the script in dry-run mode to preview the entities that will be created or updated:

```bash theme={null}
yarn run zuora-import --dry-run
```

Dry-run mode:

* Applies no changes to Stigg
* Logs all planned actions to the console

### 5. Import the catalog

Run the default import to create new entities in Stigg:

```bash theme={null}
yarn run zuora-import
```

This mode:

* Creates new entities only
* Does not update existing entities
* Creates all entities in `Draft` status

## Advanced usage

### Update existing entities

To update existing products, plans, and prices:

```bash theme={null}
yarn run zuora-import --update
```

* Creates missing entities
* Updates existing entities
* Does not publish

### Publish imported entities

To publish all unpublished entities:

```bash theme={null}
yarn run zuora-import --publish
```

This command:

* Creates missing entities
* Publishes unpublished entities
* Does not update already published entities

### Update and publish in one run

```bash theme={null}
yarn run zuora-import --update --publish
```

This command:

* Creates new entities
* Updates existing entities
* Publishes unpublished entities

### Dry-run with any mode

Dry-run can be combined with any flags:

```bash theme={null}
yarn run zuora-import --update --dry-run
yarn run zuora-import --publish --dry-run
yarn run zuora-import --update --publish --dry-run
```

### Grandfathered plan forking

Use this workflow to "freeze" an existing plan or add-on in Stigg while the next import creates a fresh copy with the latest Zuora data and all entitlements carried over. The original grandfathered entity is left untouched and can continue to be used for existing subscribers.

**Step 1 — Mark the plan or add-on as grandfathered**

Run the fork command with the `refId` of the plan or add-on you want to freeze:

```bash theme={null}
yarn run zuora-import:fork <plan-or-addon-refId>
```

This sets `GRANDFATHERED: true` in the entity's metadata and handles the draft/publish lifecycle automatically.

**Step 2 — Re-run the import**

```bash theme={null}
yarn run zuora-import --publish
```

When the script encounters a grandfathered entity it:

* Creates a new plan or add-on with a `-copy-1` suffix (e.g. `Pro_Plan-copy-1`)
* Copies all entitlements from the grandfathered version to the new one
* Leaves the grandfathered entity untouched

**Chaining forks**

You can fork a copy and re-import again — the suffix increments automatically:

| Entity            | State             | Next import result        |
| ----------------- | ----------------- | ------------------------- |
| `Pro_Plan`        | Grandfathered     | Creates `Pro_Plan-copy-1` |
| `Pro_Plan-copy-1` | Grandfathered     | Creates `Pro_Plan-copy-2` |
| `Pro_Plan-copy-2` | Not grandfathered | Updated in place          |

## Final notes

After import, plans are either left in `Draft` or published depending on the flags you use. Imported plans are marked as `Synced`, ensuring Zuora remains the authoritative source of billing data.

This setup lets you adopt Stigg incrementally, without disrupting your existing Zuora-based billing workflows.