epcc-inventory-loader

CLI tool to bulk-load inventory records into Elastic Path Composable Commerce.

Installation

npm install -g @elasticpath/epcc-inventory-loader

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. useast.api.elasticpath.com |

Optional

| Variable | Default | Description | |----------|---------|-------------| | EPCC_CLIENT_RATE_LIMIT | 3 | Maximum API requests per throttle interval | | EPCC_CLIENT_THROTTLE_INTERVAL | 125 | Throttle window in milliseconds | | EPCC_CLIENT_CON_KEEP_ALIVE | true | Enable HTTP keep-alive | | EPCC_CLIENT_CON_KEEP_ALIVE_INTERVAL | 1000 | Keep-alive interval in milliseconds |

Global Options

epcc-inventory-loader [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

Load inventory records from a JSONL file into EPCC.

epcc-inventory-loader load [options]

Options:
  -f, --file <path>                Path to the input JSONL file (required)
  --batch-size <number>            Records per processing batch (default: 500)
  --product-batch-size <number>    Products per API filter call, max 100 (default: 100)
  -l, --log-level <level>          Log level: debug|info|warn|error|off (default: info)
  -h, --help                       Show help for this command

Examples

Load inventory from a JSONL file:

epcc-inventory-loader load --file ./inventory.jsonl

Load using a .env file for credentials:

epcc-inventory-loader --env-file ./.env.production load --file ./inventory.jsonl

Load with smaller batches and debug logging:

epcc-inventory-loader load --file ./inventory.jsonl --batch-size 100 --log-level debug

Input Format

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

| Field | Type | Description | |-------|------|-------------| | action | string | Operation: increment, decrement, or matchAvailable | | sku | string | Product SKU (mutually exclusive with external_ref) | | external_ref | string | Product external reference (mutually exclusive with sku) | | quantity | number | Quantity to apply |

Example record using SKU:

{"action": "increment", "sku": "SHIRT-BLU-M", "quantity": 50}

Example record using external reference:

{"action": "matchAvailable", "external_ref": "prod-abc123", "quantity": 100}

Actions

• increment — increases existing stock or creates a new inventory record
• decrement — decreases existing stock, capped at 0; cannot create new records
• matchAvailable — sets available stock to an exact value; creates if not found

CI/CD Usage

Export credentials as environment variables and pass the input file:

# GitLab CI example
load-inventory:
  image: node:20
  script:
    - npm install -g @elasticpath/epcc-inventory-loader
    - epcc-inventory-loader load --file ./export/inventory.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 inventory records loaded successfully | | 1 | Error — see stderr output for details |