Magento 2 Skill

Connect to one or more Magento 2 / Adobe Commerce stores via REST API using OAuth 1.0a.

Authentication

All requests are signed with OAuth 1.0a. Credentials are read from environment variables — never ask the user to paste them in chat.

Single site (default)

• MAGENTO_BASE_URL — e.g. https://store.example.com
• MAGENTO_CONSUMER_KEY
• MAGENTO_CONSUMER_SECRET
• MAGENTO_ACCESS_TOKEN
• MAGENTO_ACCESS_TOKEN_SECRET

Multi-site setup

To connect to additional stores, define credentials with a site suffix (MAGENTO_\x3CVAR>_\x3CSITE>):

MAGENTO_BASE_URL_US=https://us.store.com
MAGENTO_CONSUMER_KEY_US=...
MAGENTO_CONSUMER_SECRET_US=...
MAGENTO_ACCESS_TOKEN_US=...
MAGENTO_ACCESS_TOKEN_SECRET_US=...

MAGENTO_BASE_URL_EU=https://eu.store.com
MAGENTO_CONSUMER_KEY_EU=...
...

All scripts accept --site \x3Calias> to target a specific store. When omitted, the default (unsuffixed) credentials are used.

python3 orders.py list --site us --limit 10
python3 system.py sites            # list all configured sites

Optional env vars

• MAGENTO_TIMEOUT — Default is 30 seconds. Supports per-site override: MAGENTO_TIMEOUT_US.
• MAGENTO_DEBUG — Set to 1 to enable verbose logging to stderr.

All scripts import the shared client from scripts/magento_client.py. Never construct raw HTTP requests inline — always use the client.

Available commands

Run scripts with: python3 \x3Cskill_dir>/scripts/\x3Cscript>.py [args]

Orders — scripts/orders.py

# List recent orders (default: last 20)
python3 orders.py list [--limit N] [--status pending|processing|complete|canceled|closed|holded|payment_review]

# Get a single order
python3 orders.py get \x3Corder_id>

# Update order status
python3 orders.py update-status \x3Corder_id> \x3Cstatus>

# Cancel an order
python3 orders.py cancel \x3Corder_id>

# Ship an order (optional: add tracking number and carrier)
python3 orders.py ship \x3Corder_id> [--track N] [--carrier carrier_code] [--title title]

# Invoice an order
python3 orders.py invoice \x3Corder_id>

Catalog — scripts/catalog.py

# Search products
python3 catalog.py search \x3Cquery> [--limit N]

# Get product by SKU
python3 catalog.py get \x3Csku>

# Update product price
python3 catalog.py update-price \x3Csku> \x3Cprice>

# Update product name / description
python3 catalog.py update-attribute \x3Csku> \x3Cattribute> \x3Cvalue>

# Enable or disable a product
python3 catalog.py update-status \x3Csku> {enabled|disabled}

# Delete a product
python3 catalog.py delete \x3Csku>

# List categories
python3 catalog.py categories

Customers — scripts/customers.py

# Search customers by email or name
python3 customers.py search \x3Cquery> [--limit N]

# Get customer by ID
python3 customers.py get \x3Ccustomer_id>

# Get customer orders
python3 customers.py orders \x3Ccustomer_id>

# Update customer group
python3 customers.py update-group \x3Ccustomer_id> \x3Cgroup_id>

Inventory — scripts/inventory.py

# Check stock for a SKU
python3 inventory.py check \x3Csku>

# Update stock quantity
python3 inventory.py update \x3Csku> \x3Cqty>

# List low-stock products (below threshold)
python3 inventory.py low-stock [--threshold N]

# Bulk stock check from a comma-separated SKU list
python3 inventory.py bulk-check \x3Csku1,sku2,...>

Multi-Source Inventory (MSI)

Requires Magento 2.3+ with Inventory modules enabled.

# List inventory sources (warehouses)
python3 inventory.py sources [--limit N]

# Get details for a specific source
python3 inventory.py source-get \x3Csource_code>

# List source items (stock per source) — filter by SKU, source, or both
python3 inventory.py source-items --sku \x3Csku> [--source \x3Csource_code>] [--limit N]

# Update quantity for a SKU at a specific source
python3 inventory.py source-item-update \x3Csku> \x3Csource_code> \x3Cqty>

# Get salable quantity for a SKU in a stock
python3 inventory.py salable-qty \x3Csku> \x3Cstock_id>

# Check if a product is salable in a stock
python3 inventory.py is-salable \x3Csku> \x3Cstock_id>

# List inventory stocks (logical groupings)
python3 inventory.py stocks [--limit N]

Promotions — scripts/promotions.py

# List active cart price rules
python3 promotions.py list [--active-only]

# Get a rule by ID
python3 promotions.py get \x3Crule_id>

# Create a coupon code for an existing rule
python3 promotions.py create-coupon \x3Crule_id> \x3Ccode> [--uses N]

# Disable a promotion rule
python3 promotions.py disable \x3Crule_id>

# List coupon usage stats
python3 promotions.py coupon-stats \x3Ccoupon_code>

Reporting — scripts/reports.py

# Sales summary for a date range
python3 reports.py sales --from YYYY-MM-DD --to YYYY-MM-DD

# Revenue by product (top N)
python3 reports.py top-products [--limit N] [--from YYYY-MM-DD] [--to YYYY-MM-DD]

# Revenue by customer (top N)
python3 reports.py top-customers [--limit N] [--from YYYY-MM-DD] [--to YYYY-MM-DD]

# Order status breakdown
python3 reports.py order-status [--from YYYY-MM-DD] [--to YYYY-MM-DD]

# Inventory value report
python3 reports.py inventory-value

System & Discovery — scripts/system.py

# Check API connection status
python3 system.py status

# List installed modules
python3 system.py modules

# Inspect REST schema
python3 system.py schema

# List all configured sites
python3 system.py sites

# Cache management
python3 system.py cache-list
python3 system.py cache-flush [--types ID1,ID2]

Custom API — scripts/custom_api.py

Use this for interacting with discovered custom endpoints.

# Call custom endpoints (e.g. blog module)
python3 custom_api.py GET \x3Cpath> [--params '{"key": "value"}']
python3 custom_api.py POST \x3Cpath> --data '{"body": "json"}'

Morning Brief — scripts/morning_brief.py

Generate a daily store health summary across sales, orders, inventory, promotions, and customers.

# Generate morning brief (default: last 24 hours)
python3 morning_brief.py brief [--site SITE] [--hours 24] [--stock-threshold 10]

# JSON output for programmatic consumption
python3 morning_brief.py brief --format json

Diagnostics — scripts/diagnose.py

Deep-dive analysis for specific store issues.

# Inventory risk radar with velocity-based stockout prediction
python3 diagnose.py inventory-risk [--days 7] [--threshold 10] [--limit 50]

# Audit promotions for expired rules, missing coupons, exhausted limits
python3 diagnose.py promotion-audit [--warn-hours 48]

# Find stuck orders (pending too long, payment review, processing delay)
python3 diagnose.py order-exceptions [--pending-hours 24] [--processing-hours 48]

# Detect pricing anomalies (zero price, negative price, inverted specials)
python3 diagnose.py pricing-anomaly [--limit 50]

# JSON output available for all subcommands
python3 diagnose.py inventory-risk --format json

Bulk Operations

Batch update prices, stock, and shipments via CSV or inline input.

# Bulk update prices (preview mode)
python3 catalog.py bulk-update-price --items "SKU1:29.99,SKU2:49.99"
python3 catalog.py bulk-update-price --csv prices.csv

# Execute bulk price changes
python3 catalog.py bulk-update-price --csv prices.csv --execute

# Bulk update stock
python3 inventory.py bulk-update --items "SKU1:100,SKU2:50"
python3 inventory.py bulk-update --csv stock.csv --execute

# Bulk ship orders
python3 orders.py bulk-ship --csv shipments.csv --execute

Output format

All scripts print a UTF-8 table (via tabulate) or a JSON summary to stdout. When presenting results to the user, render them as a markdown table. For single-record lookups, format as a definition list.

Error handling

Scripts exit with code 1 on API errors and print a JSON error to stderr:

{ "error": "404 Not Found", "message": "No such entity with id = 99", "url": "..." }

If a script fails, read stderr, extract the message field, and tell the user plainly what went wrong. Do not retry automatically unless the user asks.

Rules

• Never expose OAuth credentials in chat output, logs, or summaries.
• For any write operation (cancel, delete, update-price, update-status, update-group, cache-flush, ship, invoice, create-coupon, disable, source-item-update, and all POST/PUT/DELETE via custom_api.py), always repeat the full command back to the user and wait for explicit confirmation before executing.
• Read-only operations (list, get, search, check, status, modules, schema, cache-list, reports) may be executed directly without confirmation.
• When a date range is not specified for reports, default to the last 30 days.
• Monetary values are returned in the store's base currency — include the currency code in output.
• Multi-site: When multiple sites are configured, always confirm which site the user intends before executing write operations. Use system.py sites to discover available sites.
• Production Safety: After performing updates to products or prices, it is recommended to run system.py cache-flush if the changes don't appear on the frontend.
• Morning Brief and diagnose commands are read-only — they may be executed directly without confirmation.
• After generating a morning brief, proactively recommend relevant diagnose.py subcommands based on the findings.
• Bulk operations: Always preview first (default), then require --execute flag and explicit user confirmation. Follow preview templates in references/workflows.md.
• Scenarios: For detailed routing guidance, see references/workflows.md.