Skip to main content

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.

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, 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: 
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: 
    cp .env.example .env
  2. Update the following values in .env: 
    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: 
yarn install
or 
npm install
Before making any changes, run the script in dry-run mode to preview the entities that will be created or updated: 
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: 
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: 
yarn run zuora-import --update
  • Creates missing entities
  • Updates existing entities
  • Does not publish

​
Publish imported entities

To publish all unpublished entities: 
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

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: 
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: 
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 
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:
EntityStateNext import result
Pro_PlanGrandfatheredCreates Pro_Plan-copy-1
Pro_Plan-copy-1GrandfatheredCreates Pro_Plan-copy-2
Pro_Plan-copy-2Not grandfatheredUpdated 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.