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).

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

Requires permission: pricing_tiers.create

Request​

Responses​

Created

Response Headers
    Content-Type