Skip to main content
POST
Required scope: costs:write Use this when a product’s unit cost differs from the “Cost per item” synced from Shopify, or changes on a known date. Say your supplier raised the price of a variant on March 1: end-date the current line with Update a COG line, then add the new cost here with effectiveStartDate: "2026-03-01".

How an order picks its product cost

  1. A manual COG line whose window contains the order’s creation time (UTC). If several match, the one with the earliest effectiveStartDate wins.
  2. Otherwise, the cost synced from Shopify for that date.
  3. Otherwise, the Default COGS % from product defaults.
If the matching manual line has no cost, or a cost above 1,000,000, the order uses the Shopify cost instead.

What to send

  • cost (0 or more, per unit, in your store’s currency) and effectiveStartDate are required. Leave out effectiveEndDate, or send null, for an open-ended line. A date-only end date covers that whole day (UTC).
  • Use YYYY-MM-DD dates. Any string is accepted, but a line whose start date doesn’t parse as a date is never used.
  • Overlapping lines aren’t rejected. Give each line its own start date so it’s clear which one applies.
  • Each call adds a new line with a new id, so retrying a request that timed out can add the line twice. Check manualCostHistory before you retry.
  • Find productId and variantId with Search products. An unknown variant returns 404.

Response

The full variant record. The new line is the last entry in manualCostHistory; keep its id to update or delete it later. Upstack then recalculates the past orders the line covers.

Authorizations

x-api-key
string
header
required

Your Upstack API key. Starts with upstack_.

x-pixel-id
string
header
required

The pixel id the request targets.

Path Parameters

productId
string
required

Shopify product id, as returned by Search products.

variantId
string
required

Shopify variant id, as returned by Search products.

Body

application/json
cost
number
required

Per-unit cost in your store's currency.

Required range: x >= 0
effectiveStartDate
string
required

ISO 8601 date (2026-01-01) or timestamp the line starts applying. Any string is accepted, but a line whose start date doesn't parse is never used.

effectiveEndDate
string | null

ISO 8601 date or timestamp the line stops applying. Omit or send null for open-ended.

description
string

Optional note shown alongside the line.

Response

The updated variant (with the new line added to history).

variant
object
required

A stored product variant, synced from Shopify. Each variant record also carries its parent product's details, so one call gives you both.

The fields below are the ones worth relying on; the record also includes internal index keys (lowercased titles, composite ids) that you should ignore.