upstack products

Browse products + variants in the configured catalog and manage per-variant cost data. Wraps the /api/products* endpoints — see the API reference under the Products group for full request / response shapes. Mutations fire the same per-order COGS recalculation as the web UI.

Subcommands

Subcommand	Wraps
`search`	`GET /api/products/search`
`cost`	`GET /api/products/{productId}/{variantId}/cost`
`handling-fee set`	`PUT /api/products/{productId}/{variantId}/handling-fee`
`cogs add`	`POST /api/products/{productId}/{variantId}/cogs`
`cogs update`	`PUT /api/products/{productId}/{variantId}/cogs/{cogId}`
`cogs delete`	`DELETE /api/products/{productId}/{variantId}/cogs/{cogId}`

search

Search products by title / SKU / variant. Cursor-paginated.

upstack products search -q "shirt"
upstack products search -q "shirt" --page-size 50
upstack products search --cursor "<pagination.cursor from previous response>"

Flag	Description	Default
`-q, --query <term>`	Search term, matched against title / SKU / variant.
`--page-size <n>`	Results per page, 1–100.	`20`
`--cursor <cursor>`	`pagination.cursor` from a previous response. Absent once `pagination.hasMore` is `false`.

Required scope: costs:read.

cost

Show a single variant in full — identity, its parent product’s details, current price, handling fee, and both cost histories.

upstack products cost --product-id prd_123 --variant-id var_456

Required scope: costs:read.

handling-fee set

Set the per-variant handling fee, charged on every unit sold. Must be >= 0. Setting it replaces the global default handling fee for this variant — use 0 to charge no handling fee.

upstack products handling-fee set --product-id prd_123 --variant-id var_456 --fee 2
upstack products handling-fee set --product-id prd_123 --variant-id var_456 --fee 0 --yes

Required scope: costs:write.

cogs add

Append a new COG line to a variant’s manual cost history. The server assigns a ULID for the new line.

upstack products cogs add \
  --product-id prd_123 --variant-id var_456 \
  --cost 5 --start 2026-01-01 \
  --description "Q1 batch"

upstack products cogs add \
  --product-id prd_123 --variant-id var_456 \
  --cost 6 --start 2026-04-01 --end 2026-06-30

--end is optional — omit for an open-ended interval. Required scope: costs:write.

cogs update

Update an existing COG line by its server-assigned ID. Pass any combination of --cost, --start, --end, --description. Use --end null to clear an end date (make the line open-ended).

upstack products cogs update \
  --product-id prd_123 --variant-id var_456 --cog-id cog_abc \
  --cost 7

upstack products cogs update \
  --product-id prd_123 --variant-id var_456 --cog-id cog_abc \
  --end null

Required scope: costs:write.

cogs delete

Delete a COG line by its ID. The CLI prompts for confirmation; --yes (or -y) skips it.

upstack products cogs delete \
  --product-id prd_123 --variant-id var_456 --cog-id cog_abc

Required scope: costs:write.

GETTING STARTED

ACCOUNT

DISCOVERY

QUERIES

DASHBOARDS

COSTS

PRODUCTS

ADVANCED

Subcommands

search

cost

handling-fee set

cogs add

cogs update

cogs delete

​Subcommands

​search

​cost

​handling-fee set

​cogs add

​cogs update

​cogs delete

Subcommands

search

cost

handling-fee set

cogs add

cogs update

cogs delete