Skip to main content

Three-layer command system

Shoplazza CLI organizes commands into three layers, each providing a different level of control and convenience. Understanding when to use each layer helps you work more efficiently.

Overview​

Layer 1: Shortcuts      →  Human & AI friendly, smart defaults
Layer 2: API commands   →  1:1 API mapping, full parameter control
Layer 3: Raw API        →  Escape hatch, 100% endpoint coverage

Layer 1: Shortcuts​

Shortcuts are prefixed with + and designed for high-frequency operations. They provide smart defaults, named flags, and a streamlined interface.

When to use: Day-to-day operations where convenience matters more than full parameter control.

shell
# Search products — named filters, one page per call, formatted output
shoplazza products +search --keyword "shirt" --format table

# Ship an order — smart defaults for fulfillment
shoplazza orders +ship --order-id 12345 --tracking SF123456789

# Create a discount — guided flow with sensible defaults
shoplazza discounts +percent-code

Characteristics:

  • + prefix distinguishes shortcuts from API commands
  • Smart defaults reduce required flags
  • Prompts for missing required flags at an interactive terminal
  • Designed for both human developers and AI agents

Layer 2: API commands​

API commands map 1:1 to Shoplazza platform API endpoints. They provide full control over request parameters and response handling.

When to use: When you need precise control over API parameters, or when no shortcut exists for your operation.

shell
# List products with specific query parameters
shoplazza products list --params '{"per_page": 50, "published_status": "published"}'

# Create a product with full body control
shoplazza products create --data @product.json

# Filter response with jq
shoplazza orders list --format json --jq '.data.orders[] | {id, status, total_price}'

Characteristics:

  • 300+ commands auto-generated from OpenAPI spec
  • --params for path and query parameters (API commands take no positional arguments)
  • --data for request body
  • Full JSON request/response control

Layer 3: Raw API​

The api rest command provides an escape hatch to call any Shoplazza API endpoint directly.

When to use: When you need to call an endpoint not yet covered by API commands, or when you need full HTTP control.

shell
# Call any endpoint directly
shoplazza api rest GET /openapi/2026-01/products --params '{"per_page": 10}'

# POST with custom body
shoplazza api rest POST /openapi/2026-01/webhooks --data '{
  "webhook": {"topic": "orders/create", "address": "https://example.com/hook"}
}'

Characteristics:

  • Supports GET, POST, PUT, PATCH, and DELETE methods
  • Full HTTP control
  • 100% platform API coverage
  • No parameter validation (you manage the contract)

Choosing the right layer​

ScenarioRecommended layer
Search products by keywordShortcuts: products +search
Create product with 20+ fieldsAPI commands: products create
Call a brand-new API endpointRaw API: api rest
Daily order managementShortcuts: orders +ship, orders +refund
Complex discount with custom rulesAPI commands: discounts create-automatic
Debugging or exploring APIsRaw API: api rest + --dry-run

Discovery​

Use shoplazza schema to explore available commands at any layer:

shell
# See all modules
shoplazza schema

# See commands for a module
shoplazza schema products

# See full schema for a command
shoplazza schema products.list
On this page