# Three-layer command system

> The three layers of Shoplazza CLI commands — shortcuts, API commands, and raw API — what each one is good at, and how to pick one for the task at hand.

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

| Scenario | Recommended layer |
|----------|-------------------|
| Search products by keyword | Shortcuts: `products +search` |
| Create product with 20+ fields | API commands: `products create` |
| Call a brand-new API endpoint | Raw API: `api rest` |
| Daily order management | Shortcuts: `orders +ship`, `orders +refund` |
| Complex discount with custom rules | API commands: `discounts create-automatic` |
| Debugging or exploring APIs | Raw 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
```