# discounts

> Shoplazza CLI discounts commands: shortcuts for coupons, flash sales, and tiered offers, plus the API commands behind promotional campaigns on a store.

Manage discounts, coupons, and promotional campaigns. Includes 8 shortcut commands and 15 API commands.

## Shortcuts

### +search

Search existing discounts.

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

| Flag | Type | Description |
|------|------|-------------|
| `--query` | string | Search by discount name |
| `--discount-code` | string | Search by discount code |
| `--progress` | string | Progress filter: `ongoing`, `not_started`, `finished`, `paused` |
| `--discount-type` | string | Discount type filter |
| `--discount-target` | string | Target filter: `product`, `order`, `shipping` |
| `--discount-method` | string | Method filter: `automatic`, `discount_code` |
| `--page-limit` | int | Page size (1–250) |

```shell
shoplazza discounts +search
shoplazza discounts +search --query "Summer"
shoplazza discounts +search --discount-code SALE20
shoplazza discounts +search --progress ongoing --discount-type flashsale
shoplazza discounts +search --discount-target product --discount-method automatic
```

### +rebate

Create an automatic tiered rebate (spend-and-save / buy-more-save-more).

```shell
shoplazza discounts +rebate [flags]
```

| Flag | Type | Required | Description |
|------|------|----------|-------------|
| `--target` | string | Yes | Scope: `order` or `product` |
| `--tiers` | string | Yes | Threshold:discount pairs (comma-separated, e.g. `100:10,200:25`) |
| `--type` | string | | Type: `amount-off`, `amount-percent`, `qty-off`, `qty-percent` (default: `amount-off`) |
| `--products` | string | | Product IDs (comma-separated); with `--target product`, one of `--products`/`--collections`/`--variants` is required |
| `--collections` | string | | Collection IDs (mutually exclusive with `--products`) |
| `--variants` | string | | Variant IDs (mutually exclusive with `--products`) |
| `--exclude` | bool | | Treat IDs as exclusion list (default: `false`) |
| `--limit-max` | int | | Max total uses |
| `--limit-user` | int | | Max uses per user |
| `--limit-order-once` | bool | | Apply at most once per order (default: `true`; only with `--type amount-off` or `qty-off`) |
| `--combines` | string | | Combinable with: `order`, `product`, `shipping` |
| `--customer-segments` | string | | Restrict to customer segment IDs |
| `--name` | string | | Campaign name (auto-generated if omitted) |
| `--start` | string | | Start time (default: `now`) |
| `--end` | string | | End time (default: `-1`, never expires) |

```shell
# Order-level: $10 off at $100, $25 off at $200
shoplazza discounts +rebate --target order --tiers "100:10,200:25"

# Product-level: 20% off when buying 3+
shoplazza discounts +rebate --target product --type qty-percent \
  --tiers "3:20" --products "id1,id2"

# With usage limits and expiry
shoplazza discounts +rebate --target order --tiers "100:10" \
  --limit-max 1000 --limit-user 3 --start now --end "+7d"
```

### +flashsale

Create a flash sale (automatic, time-limited).

```shell
shoplazza discounts +flashsale [flags]
```

| Flag | Type | Required | Description |
|------|------|----------|-------------|
| `--value` | float | Yes | Discount value: percent → 1–99; fixed-price → new price; off → amount off |
| `--type` | string | | Type: `percent`, `fixed-price`, `off` (default: `percent`) |
| `--variants` | string | | Variant IDs (mutually exclusive with `--collections`) |
| `--collections` | string | | Collection IDs (mutually exclusive with `--variants`) |
| `--price-rule` | string | | Based on: `price` (sale price) or `compare_at_price` (default: `price`) |
| `--limit-user-variant` | int | | Max quantity per user per variant |
| `--limit-user-product` | int | | Max quantity per user per product |
| `--limit-user-all` | int | | Max quantity per user across all sale products |
| `--stock` | int | | Discount-specific stock cap |
| `--combines` | string | | Combinable with: `order`, `product`, `shipping` |
| `--customer-segments` | string | | Restrict to customer segments |
| `--name` | string | | Campaign name |
| `--start` | string | | Start time (default: `now`) |
| `--end` | string | | End time (default: `-1`) |

```shell
# 20% off sitewide
shoplazza discounts +flashsale --value 20

# Fixed price $19.99 for specific variants
shoplazza discounts +flashsale --value 19.99 --type fixed-price --variants "v1,v2"

# $5 off by collection
shoplazza discounts +flashsale --value 5 --type off --collections "c1,c2"

# With stock and user limits
shoplazza discounts +flashsale --value 30 --stock 100 --limit-user-variant 2
```

### +mn-discount

Create an Nth-item discount (buy M, get Nth at X% off).

```shell
shoplazza discounts +mn-discount [flags]
```

| Flag | Type | Required | Description |
|------|------|----------|-------------|
| `--tiers` | string | Yes | `N:percent` pairs (e.g. `2:30,3:50` — buy 2, 2nd item 30% off; buy 3, 3rd item 50% off) |
| `--scope` | string | | Apply level: `highest`, `all`, `highest-all` (default: `highest`) |
| `--products` | string | | Product IDs |
| `--collections` | string | | Collection IDs |
| `--variants` | string | | Variant IDs |
| `--exclude` | bool | | Treat IDs as exclusion list (default: `false`) |
| `--price-sort` | string | | Price sort direction: `desc` (high→low) or `asc` (default: `desc`) |
| `--combines` | string | | Combinable with: `order`, `product`, `shipping` |
| `--limit-max` | int | | Max total uses |
| `--limit-user` | int | | Max uses per user |
| `--customer-segments` | string | | Restrict to customer segments |
| `--name` | string | | Campaign name |
| `--start` | string | | Start time (default: `now`) |
| `--end` | string | | End time (default: `-1`) |

```shell
# Buy 2, 2nd item 30% off; buy 3, 3rd item 50% off
shoplazza discounts +mn-discount --tiers "2:30,3:50"

# Scoped to specific products
shoplazza discounts +mn-discount --tiers "3:50" --products "id1,id2"
```

### +percent-code

Create a percentage-off discount code.

```shell
shoplazza discounts +percent-code [flags]
```

| Flag | Type | Required | Description |
|------|------|----------|-------------|
| `--target` | string | Yes | Scope: `order` or `product` |
| `--percent` | float | Yes | Discount percentage (1–99) |
| `--products` | string | | Product IDs (with `--target product`, one of `--products`/`--variants`/`--collections` is required) |
| `--variants` | string | | Variant IDs |
| `--collections` | string | | Collection IDs |
| `--exclude` | bool | | Treat IDs as exclusion list |
| `--min-amount` | float | | Minimum order amount (for `target=order`) |
| `--min-quantity` | int | | Minimum item quantity (for `target=product`, default: `1`) |
| `--code` | string | | Discount code (auto-generated if omitted) |
| `--combines` | string | | Combinable with: `order`, `product`, `shipping` |
| `--limit-max` | int | | Max total uses |
| `--limit-user` | int | | Max uses per user |
| `--customer-segments` | string | | Restrict to customer segments |
| `--name` | string | | Campaign name |
| `--start` | string | | Start time (default: `now`) |
| `--end` | string | | End time (default: `-1`) |

```shell
# Order-level 20% off
shoplazza discounts +percent-code --target order --percent 20

# Product-level 15% off for specific products
shoplazza discounts +percent-code --target product --percent 15 --products "id1,id2"

# Custom code with limits
shoplazza discounts +percent-code --target order --percent 10 --code SAVE10 \
  --min-amount 50 --limit-max 500 --limit-user 1
```

### +amount-code

Create a fixed-amount-off discount code.

```shell
shoplazza discounts +amount-code [flags]
```

| Flag | Type | Required | Description |
|------|------|----------|-------------|
| `--target` | string | Yes | Scope: `order` or `product` |
| `--off` | float | Yes | Fixed amount off |
| `--products` | string | | Product IDs (with `--target product`, one of `--products`/`--variants`/`--collections` is required) |
| `--variants` | string | | Variant IDs |
| `--collections` | string | | Collection IDs |
| `--exclude` | bool | | Treat IDs as exclusion list |
| `--min-amount` | float | | Minimum order amount |
| `--min-quantity` | int | | Minimum item quantity (default: `1`) |
| `--limit-order-once` | bool | | Apply at most once per order (default: `true`) |
| `--code` | string | | Discount code |
| `--combines` | string | | Combinable with: `order`, `product`, `shipping` |
| `--limit-max` | int | | Max total uses |
| `--limit-user` | int | | Max uses per user |
| `--customer-segments` | string | | Restrict to customer segments |
| `--name` | string | | Campaign name |
| `--start` | string | | Start time (default: `now`) |
| `--end` | string | | End time (default: `-1`) |

```shell
# Order-level $10 off
shoplazza discounts +amount-code --target order --off 10

# Product-level $5 off, min 2 items
shoplazza discounts +amount-code --target product --off 5 --min-quantity 2 --products "id1"

# Custom code with minimum order
shoplazza discounts +amount-code --target order --off 20 --code OFF20 --min-amount 100
```

### +bxgy-code

Create a buy-X-get-Y discount code.

```shell
shoplazza discounts +bxgy-code [flags]
```

| Flag | Type | Required | Description |
|------|------|----------|-------------|
| `--products` | string | | Buy-side product IDs (one of `--products`/`--variants`/`--collections` is required) |
| `--variants` | string | | Buy-side variant IDs |
| `--collections` | string | | Buy-side collection IDs |
| `--exclude` | bool | | Treat buy-side IDs as exclusion list |
| `--buy-quantity` | int | | Trigger quantity (exactly one of `--buy-quantity`/`--buy-amount` is required) |
| `--buy-amount` | float | | Trigger amount (mutually exclusive with `--buy-quantity`) |
| `--get-products` | string | | Get-side product IDs (one of `--get-products`/`--get-variants`/`--get-collections` is required) |
| `--get-variants` | string | | Get-side variant IDs |
| `--get-collections` | string | | Get-side collection IDs |
| `--get-quantity` | int | Yes | Number of get items |
| `--get-percent` | int | | Get-side discount % (1–99; one of percent/off/free required) |
| `--get-off` | float | | Get-side fixed amount off |
| `--get-free` | bool | | Get items for free |
| `--code` | string | | Discount code |
| `--limit-order` | int | | Max applications per order (default: `1`, `-1` for unlimited) |
| `--combines` | string | | Combinable with: `order`, `product`, `shipping` |
| `--limit-max` | int | | Max total uses |
| `--limit-user` | int | | Max uses per user |
| `--customer-segments` | string | | Restrict to customer segments |
| `--name` | string | | Campaign name |
| `--start` | string | | Start time (default: `now`) |
| `--end` | string | | End time (default: `-1`) |

```shell
# Buy 3 of product A, get 1 of product B free
shoplazza discounts +bxgy-code --products "prodA" --buy-quantity 3 \
  --get-products "prodB" --get-quantity 1 --get-free

# Spend $100 on A, get B at 50% off
shoplazza discounts +bxgy-code --products "prodA" --buy-amount 100 \
  --get-products "prodB" --get-quantity 1 --get-percent 50
```

### +free-shipping-code

Create a free shipping discount code.

```shell
shoplazza discounts +free-shipping-code [flags]
```

| Flag | Type | Description |
|------|------|-------------|
| `--off` | float | Shipping discount amount (omit for full free shipping) |
| `--min-amount` | float | Minimum order amount (mutually exclusive with `--min-quantity`) |
| `--min-quantity` | int | Minimum item quantity (mutually exclusive with `--min-amount`) |
| `--countries` | string | ISO country codes (comma-separated) or `all` |
| `--code` | string | Discount code |
| `--combines` | string | Combinable with: `order`, `product`, `shipping` |
| `--limit-max` | int | Max total uses |
| `--limit-user` | int | Max uses per user |
| `--customer-segments` | string | Restrict to customer segments |
| `--name` | string | Campaign name |
| `--start` | string | Start time (default: `now`) |
| `--end` | string | End time (default: `-1`) |

```shell
# Full free shipping
shoplazza discounts +free-shipping-code

# $5 off shipping
shoplazza discounts +free-shipping-code --off 5

# Free shipping over $100
shoplazza discounts +free-shipping-code --min-amount 100

# Specific countries with custom code
shoplazza discounts +free-shipping-code --countries US,CA --code FREESHIP
```

## API commands

All dynamic API commands share these flags:

| Flag | Short | Description |
|------|-------|-------------|
| `--params` | | Path/query parameters as JSON |
| `--data` | | Request body as JSON (inline, `@file`, or `-` for stdin); only on commands that take a request body |
| `--jq` | `-q` | jq expression to filter output |
| `--dry-run` | | Preview the request without executing |



```shell
shoplazza discounts list
shoplazza discounts get --params '{"id":"123"}'
shoplazza discounts create-automatic --data @discount.json
shoplazza discounts create-non-automatic --data @discount.json
shoplazza discounts update-automatic --params '{"id":"123"}' --data @discount.json
shoplazza discounts update-non-automatic --params '{"id":"123"}' --data @discount.json
shoplazza discounts delete --params '{"id":"123"}'
shoplazza discounts batch-delete --data '{"ids":["123","456"]}'
shoplazza discounts get-by-code --params '{"discount_code":"SALE20"}'
shoplazza discounts cancel --data '{"ids":["123"]}'
shoplazza discounts restart --data '{"id":"123"}'
shoplazza discounts combine --data @combine.json
```

### discounts coupons

```shell
shoplazza discounts coupons create --data @coupon.json
shoplazza discounts coupons get --params '{"id":"123"}'
shoplazza discounts coupons update --params '{"id":"123"}' --data @coupon.json
```

## Schema introspection

```shell
shoplazza schema discounts
shoplazza schema discounts.create-automatic
```