epcc-node-importer

CLI tool to import canonical PIM hierarchy nodes into Elastic Path Composable Commerce.

Installation

npm install -g @elasticpath/epcc-node-importer

Prerequisites

Set the following environment variables before running any command. Use a .env file with --env-file or export them directly in your shell or CI environment.

Required

| Variable | Description | |----------|-------------| | EPCC_CLIENT_ID | Client ID from your EPCC store credentials | | EPCC_CLIENT_SECRET | Client secret from your EPCC store credentials | | EPCC_API_DOMAIN | EPCC API domain, e.g. api.elasticpath.com |

Optional

| Variable | Default | Description | |----------|---------|-------------| | EPCC_CLIENT_RATE_LIMIT | 6 | Maximum concurrent API requests per interval | | EPCC_CLIENT_THROTTLE_INTERVAL | 250 | Throttle window in milliseconds | | EPCC_CLIENT_KEEP_ALIVE_INTERVAL | 10000 | HTTP keep-alive interval in milliseconds | | MAX_HIERARCHY_DEPTH | 3 | Maximum depth to traverse when resolving parent node slugs |

Global Options

epcc-node-importer [options] <command>

Options:
  --env-file <path>   Path to a .env file to load (default: .env in cwd if present)
  -V, --version       Print version number
  -h, --help          Show help

Commands

load

Import nodes from a JSONL or gzip-compressed JSONL file into EPCC hierarchies.

epcc-node-importer load [options]

Options:
  -f, --file <path>                Path to the input .jsonl or .jsonl.gz file (required)
  --max-hierarchy-depth <number>   Maximum depth for resolving parent node slugs (default: 3)
  -l, --log-level <level>          Log level: debug|info|warn|error|off (default: info)
  -h, --help                       Show help for this command

Examples

Load nodes from a plain JSONL file:

epcc-node-importer load --file ./nodes.jsonl

Load from a gzip-compressed file with debug logging:

epcc-node-importer load --file ./nodes.jsonl.gz --log-level debug

Load using a .env file for credentials:

epcc-node-importer --env-file ./.env.production load --file ./nodes.jsonl

Load with a deeper hierarchy (useful for deeply nested category trees):

epcc-node-importer load --file ./nodes.jsonl --max-hierarchy-depth 5

Input Format

The input file must be JSONL (one JSON object per line) following the canonical PIM node schema. Each record represents a single hierarchy node.

Minimal node record:

{"slug": "tops", "name": "Tops", "hierarchySlug": "clothing"}

Node with a parent (creates as a child of the tops node):

{"slug": "mens-tops", "name": "Men's Tops", "hierarchySlug": "clothing", "parentSlug": "tops"}

Node with localized names and attributes:

{
  "slug": "mens-tops",
  "name": "Men's Tops",
  "hierarchySlug": "clothing",
  "parentSlug": "tops",
  "locales": {
    "fr-FR": { "name": "Hauts homme" },
    "de-DE": { "name": "Herren Oberteile" }
  },
  "attributes": {
    "featured": true
  }
}

Important: Nodes are imported serially in file order. Parent nodes must appear before their children in the file.

CI/CD Usage

Export credentials as environment variables and pass the input file:

# GitLab CI example
import-nodes:
  image: node:20
  script:
    - npm install -g @elasticpath/epcc-node-importer
    - epcc-node-importer load --file ./export/nodes.jsonl
  variables:
    EPCC_CLIENT_ID: $EPCC_CLIENT_ID
    EPCC_CLIENT_SECRET: $EPCC_CLIENT_SECRET
    EPCC_API_DOMAIN: $EPCC_API_DOMAIN

Exit Codes

| Code | Meaning | |------|---------| | 0 | All nodes imported successfully | | 1 | Error — see stderr output for details |