epcc-product-importer CLI

A command-line tool for loading and exporting products to and from Elastic Path Composable Commerce (EPCC).

Installation

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

Or via yarn:

yarn global add @elasticpath/epcc-product-importer

Prerequisites

Required Environment Variables

Set these before running any command. They can be provided via shell environment, CI/CD secrets, or a .env file (see --env-file).

| Variable | Required | Description | |----------|----------|-------------| | EPCC_CLIENT_ID | Yes | Your EPCC store Client ID | | EPCC_CLIENT_SECRET | Yes | Your EPCC store Client Secret | | EPCC_API_DOMAIN | Yes | Your EPCC API host (e.g. useast.api.elasticpath.com) |

Optional Throttle Overrides

These tune how aggressively the CLI calls the EPCC API. The defaults are appropriate for most stores.

| Variable | Default | Description | |----------|---------|-------------| | EPCC_CLIENT_RATE_LIMIT | 6 | Max API calls per interval | | EPCC_CLIENT_THROTTLE_INTERVAL | 250 | Throttle window in milliseconds | | EPCC_CLIENT_KEEP_ALIVE_INTERVAL | 10000 | HTTP keep-alive interval in milliseconds |

Global Options

These options are placed before the subcommand:

| Option | Description | |--------|-------------| | --env-file <path> | Load a .env file before running. Useful for local development. | | --version | Print the installed version and exit. |

Commands

load — Import products from a JSONL file

Streams product records from a JSON Lines file (plain or gzipped) and loads them into EPCC.

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

| Option | Alias | Default | Description | |--------|-------|---------|-------------| | --file <path> | -f | — | Required. Path to a .jsonl or .jsonl.gz input file | | --batch-size <n> | -b | 500 | Number of products per import batch | | --merge | -m | false | Merge with existing products instead of overwriting | | --dump-csv | — | false | Write intermediate CSV files to disk (for debugging) | | --log-level <level> | -l | info | Log verbosity: debug | info | warn | error | off | | --pre-process <script> | — | — | Path to a JS module for transforming each batch before import (see below) |

Pre-processing hook

The --pre-process option accepts a path to a JavaScript module that exports an async function. The function receives an array of canonical product objects and must return a (possibly modified) array:

// transform.js
module.exports = async function (products) {
  return products.map((p) => ({
    ...p,
    name: p.name.map((n) => ({ ...n, value: n.value.trim() })),
  }));
};

epcc-product-importer load --file products.jsonl --pre-process ./transform.js

Examples

# Load all products from a plain JSONL file
epcc-product-importer load --file products.jsonl

# Load from a gzipped file with a smaller batch size
epcc-product-importer load --file products.jsonl.gz --batch-size 250

# Merge (update) existing products instead of replacing
epcc-product-importer load --file products.jsonl --merge

# Load using credentials from a local .env file (for development)
epcc-product-importer --env-file .env.local load --file products.jsonl

# Debug mode: verbose logging and write intermediate CSV files
epcc-product-importer load --file products.jsonl --log-level debug --dump-csv

export — Export products to a JSONL file

Exports products from EPCC to the canonical JSON Lines format. Can export all products or a filtered subset.

epcc-product-importer export --output <path> [options]

| Option | Alias | Default | Description | |--------|-------|---------|-------------| | --output <path> | -o | — | Required. Path to write the output .jsonl file | | --products <ids> | — | all | Comma-separated product identifiers to export | | --key <field> | — | sku | Identifier field: sku | external_ref | slug | | --concurrency <n> | — | 20 | Number of concurrent export requests | | --log-level <level> | -l | info | Log verbosity: debug | info | warn | error | off |

Examples

# Export all products
epcc-product-importer export --output all-products.jsonl

# Export specific products by SKU
epcc-product-importer export --output subset.jsonl --products SKU1,SKU2,SKU3

# Export by external_ref instead of SKU
epcc-product-importer export --output by-ref.jsonl --products REF1,REF2 --key external_ref

# Export with higher concurrency for large catalogs
epcc-product-importer export --output out.jsonl --concurrency 50

Input Format

Input files must be JSON Lines (one JSON object per line) conforming to the canonical product schema. Both plain .jsonl and gzip-compressed .jsonl.gz files are supported — the format is detected automatically from the file extension.

Each line represents one product with the following top-level structure:

{
  "sku": "PROD-001",
  "name": [{ "language": "en", "value": "Product Name" }],
  "description": [{ "language": "en", "value": "Product description" }],
  "status": "live",
  "templateAttributes": [],
  "skuProducts": []
}

Refer to the canonical model schema for the full specification.

Exit Codes

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

Error details are written to stderr.

CI/CD Usage

# Set credentials from your CI/CD secrets manager
export EPCC_CLIENT_ID=<your-client-id>
export EPCC_CLIENT_SECRET=<your-client-secret>
export EPCC_API_DOMAIN=useast.api.elasticpath.com

epcc-product-importer load --file products.jsonl --batch-size 500