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_<VAR>_<SITE>):

text

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 <alias> to target a specific store. When omitted, the default (unsuffixed) credentials are used.

text

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 <skill_dir>/scripts/<script>.py [args]

Orders — scripts/orders.py#

text

# 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 <order_id>

# Update order status
python3 orders.py update-status <order_id> <status>

# Cancel an order
python3 orders.py cancel <order_id>

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

# Invoice an order
python3 orders.py invoice <order_id>

Catalog — scripts/catalog.py#

text

# Search products
python3 catalog.py search <query> [--limit N]

# Get product by SKU
python3 catalog.py get <sku>

# Update product price
python3 catalog.py update-price <sku> <price>

# Update product name / description
python3 catalog.py update-attribute <sku> <attribute> <value>

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

# Delete a product
python3 catalog.py delete <sku>

# List categories
python3 catalog.py categories

Customers — scripts/customers.py#

text

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

# Get customer by ID
python3 customers.py get <customer_id>

# Get customer orders
python3 customers.py orders <customer_id>

# Update customer group
python3 customers.py update-group <customer_id> <group_id>

Inventory — scripts/inventory.py#

text

# Check stock for a SKU
python3 inventory.py check <sku>

# Update stock quantity
python3 inventory.py update <sku> <qty>

# 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 <sku1,sku2,...>

Multi-Source Inventory (MSI)

Requires Magento 2.3+ with Inventory modules enabled.

text

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

# Get details for a specific source
python3 inventory.py source-get <source_code>

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

# Update quantity for a SKU at a specific source
python3 inventory.py source-item-update <sku> <source_code> <qty>

# Get salable quantity for a SKU in a stock
python3 inventory.py salable-qty <sku> <stock_id>

# Check if a product is salable in a stock
python3 inventory.py is-salable <sku> <stock_id>

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

Promotions — scripts/promotions.py#

text

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

# Get a rule by ID
python3 promotions.py get <rule_id>

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

# Disable a promotion rule
python3 promotions.py disable <rule_id>

# List coupon usage stats
python3 promotions.py coupon-stats <coupon_code>

Reporting — scripts/reports.py#

text

# 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#

text

# 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.

text

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

Morning Brief — scripts/morning_brief.py#

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

text

# 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.

text

# 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.

text

# 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:

json

{ "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.