> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upstackdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# upstack costs

> Read and update cost configuration from the CLI — global overrides, shipping method, and per-type cost lines (order / gateway / shipping / variable / fixed).

Manage cost configuration that drives every margin calculation in the dashboard. Wraps the `/api/costs*` endpoints — see the [API reference](/api-reference/overview) under the **Costs** group for full request / response shapes.

Mutations trigger the same per-order COGS recalculation flow as the web UI — so CLI-driven changes update existing orders identically.

## Subcommands

| Subcommand                                    | Wraps                                    |
| --------------------------------------------- | ---------------------------------------- |
| [`show`](#show)                               | `GET /api/costs`                         |
| [`global-override set`](#global-override-set) | `PUT /api/costs/global-product-override` |
| [`shipping set`](#shipping-set)               | `PUT /api/costs/shipping-settings`       |
| [`lines add`](#lines-add)                     | `POST /api/costs/lines`                  |
| [`lines update`](#lines-update)               | `PUT /api/costs/lines/{lineId}`          |
| [`lines delete`](#lines-delete)               | `DELETE /api/costs/lines/{lineId}`       |

## show

Print the full cost configuration as JSON, or filter to a single type.

```bash theme={null}
upstack costs show
upstack costs show --type shipping
```

`--type` values: `global_product_override`, `order`, `gateway`, `shipping`, `variable`, `fixed`.

**Required scope:** `costs:read`.

## global-override set

Update the default COGS / handling fee applied to product variants that have no per-variant COG line. At least one of `--default-cogs`, `--handling-fee`, or `--currency` is required.

```bash theme={null}
upstack costs global-override set --default-cogs 5 --handling-fee 1.5 --currency USD
upstack costs global-override set --default-cogs 0 --yes
```

The CLI prints a confirmation summary; `--yes` (or `-y`) skips it.

**Required scope:** `costs:write`.

## shipping set

Switch the shipping cost attribution method.

```bash theme={null}
upstack costs shipping set --method fixed_rate --fixed-rate 7.5 --currency USD
upstack costs shipping set --method shopify_charges --yes
```

`--method` values: `shopify_charges`, `fixed_rate`, `shipping_profiles`. `--fixed-rate` is required when `--method=fixed_rate`.

**Required scope:** `costs:write`.

## lines add

Add a cost line for one of the five line-typed cost surfaces — `order`, `gateway`, `shipping` (profile rule), `variable`, or `fixed`. The line body shape depends on `--type`; supply it as a JSON file via `--from-file`. The server assigns a ULID for the new line.

```bash theme={null}
upstack costs lines add --type variable --from-file marketing.json
upstack costs lines add --type gateway  --from-file shopify-payments.json
upstack costs lines add --type fixed    --from-file klaviyo-subscription.json
```

Example `marketing.json` for a `variable` line ("% of ad spend"):

```json theme={null}
{
  "name": "Google Ads — % of spend",
  "type": "pct_ad_spend",
  "percentRate": 2,
  "category": "marketing",
  "channel": "online",
  "currency": "USD"
}
```

Example `shopify-payments.json` for a `gateway` line:

```json theme={null}
{
  "name": "Shopify Payments",
  "gatewayName": "shopify_payments",
  "flatAmount": 0.30,
  "percentRate": 2.9,
  "currency": "USD"
}
```

Example `klaviyo-subscription.json` for a `fixed` line:

```json theme={null}
{
  "name": "Klaviyo subscription",
  "flatAmount": 500,
  "frequencyUnit": "month",
  "frequencyInterval": 1,
  "category": "opex",
  "currency": "USD"
}
```

See the [API reference](/api-reference/overview) under **Costs** for the full field set of each cost type (`OrderCostLine`, `GatewayCostLine`, `ShippingProfileCostLine`, `VariableCostLine`, `FixedCostLine`).

**Required scope:** `costs:write`.

## lines update

Update an existing cost line by its server-assigned ULID. The JSON file contains a partial update — any subset of the fields valid for that cost type. Omitted fields stay as-is.

```bash theme={null}
# patch.json: { "percentRate": 2.5 }
upstack costs lines update --type variable --line-id 01JZX... --from-file patch.json
```

**Required scope:** `costs:write`.

## lines delete

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

```bash theme={null}
upstack costs lines delete --type variable --line-id 01JZX...
upstack costs lines delete --type variable --line-id 01JZX... --yes
```

**Required scope:** `costs:write`.