# 订单

> Shoplazza CLI 的 orders 命令：搜索类快捷命令，以及发货、运单号、退款、取消和物流相关的 API 命令。

管理订单、履约、退款和物流。包含 5 个快捷命令和 36 个 API 命令。

## 快捷命令

### +search

按关键词、状态或日期范围搜索订单。

```shell
shoplazza orders +search [flags]
```

| 参数 | 类型 | 说明 |
|------|------|------|
| `--keyword` | string | 订单号、客户姓名、邮箱等 |
| `--status` | string | 订单状态：`opened`、`placed`、`finished`、`cancelled` |
| `--financial-status` | string | 财务状态：`waiting`、`paying`、`authorized`、`partially_paid`、`paid`、`cancelled`、`failed`、`refunded` |
| `--fulfillment-status` | string | 发货状态：`initialled`、`waiting`、`partially_shipped`、`shipped`、`finished`、`cancelled`、`returned` |
| `--customer-id` | string | 按客户 ID 过滤 |
| `--since` | string | 开始时间（ISO 日期或 unix 时间戳） |
| `--until` | string | 结束时间（ISO 日期或 unix 时间戳） |
| `--page-limit` | int | 页面大小（1–250） |

```shell
shoplazza orders +search
shoplazza orders +search --keyword "John"
shoplazza orders +search --status opened --financial-status paid
shoplazza orders +search --since 2026-01-01 --until 2026-06-30
shoplazza orders +search --customer-id <id> --page-limit 50
```

### +count

按条件统计订单数量。

```shell
shoplazza orders +count [flags]
```

| 参数 | 类型 | 说明 |
|------|------|------|
| `--status` | string | 订单状态过滤 |
| `--financial-status` | string | 财务状态过滤 |
| `--fulfillment-status` | string | 发货状态过滤 |
| `--since` | string | 开始时间 |
| `--until` | string | 结束时间 |

```shell
shoplazza orders +count
shoplazza orders +count --status opened --financial-status paid
shoplazza orders +count --since 2026-01-01 --until 2026-06-30
```

### +ship

为订单创建履约发货。

```shell
shoplazza orders +ship [flags]
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `--order-id` | string | 是 | 订单 ID |
| `--tracking` | string | 是 | 物流单号 |
| `--company` | string | | 物流公司名称（如 DHL、UPS） |
| `--company-code` | string | | 物流公司代码 |
| `--line-items` | string | | 行项目数量（格式：`line-id:qty,...`；默认全部） |
| `--notify` | bool | | 通知客户 |

```shell
shoplazza orders +ship --order-id <id> --tracking 1234567890
shoplazza orders +ship --order-id <id> --tracking 1234567890 --company DHL --notify
shoplazza orders +ship --order-id <id> --tracking 1234567890 --line-items "line1:2,line2:1"
```

### +refund

为订单创建退款。

```shell
shoplazza orders +refund [flags]
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `--order-id` | string | 是 | 订单 ID |
| `--amount` | string | 是 | 退款金额（如 `29.99`） |
| `--payment-line-id` | string | | 支付行 ID（多支付行时必填） |
| `--note` | string | | 退款备注 |
| `--return-items` | bool | | 同时退还库存 |

```shell
shoplazza orders +refund --order-id <id> --amount 29.99
shoplazza orders +refund --order-id <id> --amount 29.99 --note "客户要求" --return-items
shoplazza orders +refund --order-id <id> --amount 29.99 --payment-line-id <id>
```

### +update-tracking

更新履约的物流追踪信息。

```shell
shoplazza orders +update-tracking [flags]
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `--order-id` | string | 是 | 订单 ID |
| `--fulfillment-id` | string | 是 | 履约 ID |
| `--tracking` | string | 是 | 新物流单号 |
| `--company` | string | | 物流公司名称 |
| `--tracking-url` | string | | 自定义物流追踪 URL |
| `--notify` | bool | | 通知客户 |

```shell
shoplazza orders +update-tracking --order-id <id> --fulfillment-id <id> --tracking NEW123
shoplazza orders +update-tracking --order-id <id> --fulfillment-id <id> --tracking NEW123 \
  --company UPS --tracking-url "https://..." --notify
```

## API 命令

所有动态 API 命令共享以下参数：

| 参数 | 短参 | 说明 |
|------|------|------|
| `--params` | | 路径/查询参数（JSON 格式） |
| `--data` | | 请求体（JSON 格式） |
| `--jq` | `-q` | jq 表达式过滤输出 |
| `--dry-run` | | 预览请求，不实际执行 |

### orders

```shell
shoplazza orders list
shoplazza orders get --params '{"order_id":"123"}'
shoplazza orders get-by-number --params '{"number":"1001"}'
shoplazza orders create --data @order.json
shoplazza orders update --params '{"order_id":"123"}' --data @order.json
shoplazza orders delete --params '{"order_id":"123"}'
shoplazza orders cancel --params '{"order_id":"123"}'
shoplazza orders pay --params '{"order_id":"123"}'
shoplazza orders count
```

### orders fulfillments

```shell
shoplazza orders fulfillments list --params '{"order_id":"123"}'
shoplazza orders fulfillments get --params '{"order_id":"123","fulfillment_id":"456"}'
shoplazza orders fulfillments create --params '{"order_id":"123"}' --data @fulfillment.json
shoplazza orders fulfillments update --params '{"order_id":"123","fulfillment_id":"456"}' --data @fulfillment.json
shoplazza orders fulfillments complete --params '{"order_id":"123","fulfillment_id":"456"}'
shoplazza orders fulfillments cancel --params '{"order_id":"123","fulfillment_id":"456"}'
shoplazza orders fulfillments count --params '{"order_id":"123"}'
```

### orders refunds

```shell
shoplazza orders refunds list --params '{"order_id":"123"}'
shoplazza orders refunds list-by-order --params '{"order_id":"123"}'
shoplazza orders refunds create --data @refund.json
shoplazza orders refunds count
```

### orders post-sales

```shell
shoplazza orders post-sales list
shoplazza orders post-sales delete --params '{"id":"123"}'
```

### orders risks

```shell
shoplazza orders risks list --params '{"order_id":"123"}'
shoplazza orders risks get --params '{"order_id":"123","risk_id":"456"}'
shoplazza orders risks create --params '{"order_id":"123"}' --data @risk.json
shoplazza orders risks update --params '{"order_id":"123","risk_id":"456"}' --data @risk.json
shoplazza orders risks delete --params '{"order_id":"123","risk_id":"456"}'
```

### orders transactions

```shell
shoplazza orders transactions list --params '{"order_id":"123"}'
```

### orders shipping-schemas

```shell
shoplazza orders shipping-schemas get-general
shoplazza orders shipping-schemas save-general --data @schema.json
shoplazza orders shipping-schemas create-zone --data @zone.json
shoplazza orders shipping-schemas update-zone --params '{"id":"123"}' --data @zone.json
shoplazza orders shipping-schemas delete-zone --params '{"id":"123"}'
shoplazza orders shipping-schemas get-available-lines
```

### orders tracking-carriers

```shell
shoplazza orders tracking-carriers list
shoplazza orders tracking-carriers detect --data '{"tracking_number":"1234567890"}'
```

## Schema 自省

```shell
shoplazza schema orders
shoplazza schema orders.fulfillments.create
```