Skip to main content

Create Pricing Tier

POST 
/api/product-pricing-tiers

Create a new product pricing tier. Supports both absolute and relative pricing.

Required scope: products:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Authentication: Requires Bearer token.

Request body fields:

  • name (required, string, max:255) — unique name for the tier
  • currency_code (required) — must exist in currencies table (e.g. USD, EUR). Relative tiers inherit currency from their base tier.
  • pricing_type (required) — absolute or relative. Defaults to absolute if omitted.
  • base_pricing_tier_id (required if pricing_type=relative, nullable) — the base tier to derive pricing from; must not create a circular reference
  • adjustment_percentage (required if pricing_type=relative, nullable, numeric -99.9999 to 999.9999) — percentage adjustment relative to the base tier
  • adjustment_fixed_amount (optional, nullable, numeric) — fixed amount adjustment
  • rounding_value (optional, nullable, numeric, gt:0) — round the final price to the nearest multiple of this value

Validation rules:

  • A tier cannot reference itself as a base tier
  • Circular references are prevented
  • The default tier cannot be set to relative pricing type

Relative tiers (pricing_type=relative) require relative_basis, one of:

  • pricing_tier — derive from another tier's price. Requires base_pricing_tier_id + adjustment_percentage.
  • supplier_pricing_tier — cost-plus from the product's primary supplier cost. Optional base_supplier_pricing_tier_id (defaults to the default supplier tier) + adjustment_percentage.
  • attribute — derive from a numeric/integer product attribute: value × attr_rate + attr_offset. Requires base_attribute_id + attr_rate (optional attr_offset).
  • average_cost — cost-plus from the product's average cost: the landed figure SKU.io maintains from received stock, so inbound freight, duty and customs are included once recorded. Requires adjustment_percentage; no base field. Products with no average cost yet get no price, and a cost that falls to zero (sold out) leaves the last price standing.

rounding_value and adjustment_fixed_amount apply to every basis. Supplier/pricing-tier bases inherit currency from their source, the average-cost basis uses the default currency; attribute basis uses currency_code.

Adjustment mode (adjustment_mode, optional, markup | margin, default markup) — how adjustment_percentage is applied on the percentage bases. markup: price = base × (1 + p%). margin: price = base ÷ (1 − p%), so p% of the sell price is margin over the base (the repricer's target-margin strategy); p must be below 100.

Price bounds (floor_pricing_tier_id, ceiling_pricing_tier_id, optional, relative tiers only) — clamp the computed price to another tier's price for the same product, e.g. never below a Cost tier, never above a MAP tier. Applied after rounding and the fixed amount; if the two cross the ceiling wins. A bound tier may not be this tier or anything that derives from it (circular reference), and a tier used as a bound cannot be deleted while tiers clamp to it. Bound changes re-price the tier, and a price change on a bound tier re-clamps every tier bounded by it.

Requires permission: pricing_tiers.create

Request​

Responses​

Created

Response Headers
    Content-Type