epcc-product-association-importer

Load node-product associations into Elastic Path Composable Commerce (EPCC) from JSON Lines files.

Installation

npm install -g @elasticpath/epcc-product-association-importer
# or
yarn global add @elasticpath/epcc-product-association-importer

Prerequisites

The following environment variables are required. Set them in your shell, CI/CD secrets manager, or a .env file:

| Variable | Description | |----------|-------------| | EPCC_CLIENT_ID | Your EPCC API client ID | | EPCC_CLIENT_SECRET | Your EPCC API client secret | | EPCC_API_DOMAIN | EPCC API hostname (no protocol), e.g. useast.api.elasticpath.com |

Optional throttle overrides:

| Variable | Default | Description | |----------|---------|-------------| | EPCC_CLIENT_RATE_LIMIT | 6 | Max concurrent API requests | | EPCC_CLIENT_THROTTLE_INTERVAL | 250 | Throttle window in milliseconds | | EPCC_CLIENT_KEEP_ALIVE_INTERVAL | 10000 | HTTPS keep-alive interval in milliseconds |

Global Options

| Option | Description | |--------|-------------| | --env-file <path> | Load a .env file before running (default: .env in current directory if present) | | --version | Print version and exit | | --help | Print usage and exit |

Commands

load

Load node-product associations from a JSONL file into EPCC.

epcc-product-association-importer load --file <path> [options]

| Option | Default | Description | |--------|---------|-------------| | -f, --file <path> | (required) | Path to the input JSONL file | | -b, --batch-size <n> | 25 | Associations processed per batch | | -l, --log-level <level> | info | Log verbosity: debug\|info\|warn\|error\|off |

Input Format

Each line of the input file must be a JSON object matching the canonical model:

{"hierarchySlug": "main-catalog", "slug": "power-tools", "products": ["SKU-001", "SKU-002"]}

Examples

# Load with a local .env file
epcc-product-association-importer --env-file .env load --file associations.jsonl

# Override batch size and set verbose logging
epcc-product-association-importer load --file data.jsonl --batch-size 50 --log-level debug

# Use environment variables from shell (no .env file needed)
EPCC_CLIENT_ID=xxx EPCC_CLIENT_SECRET=yyy EPCC_API_DOMAIN=useast.api.elasticpath.com \
  epcc-product-association-importer load --file data.jsonl

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Error (credentials missing, file not found, API error, etc.) |