Skip to main content

Update Clearance Plan

PUT 

/api/v2/clearance-plans/:clearancePlan

Change an active plan's settings or ladder. Partial: send only the fields that change. Sending steps replaces the whole ladder. Adding a price tier saves the enrolled products' current price in that tier as their original price. Narrowing the scope — removing a price tier from price_tier_ids or a channel from integration_instance_ids — takes those listings out of the plan: for products the plan already marked down, the compare-at ("was") price it set is cleared on those listings (pushed straight away and retried on later price pushes until the channel confirms), and open suggestions for a removed price tier are skipped with the reason "Price tier removed from the plan". Ended plans cannot be changed (422).

Required scope: products:write

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

Body (all optional):

  • name (string, max 120; cannot be blank when sent)
  • price_tier_ids (optional, array of integer price tier ids): the price tiers the plan marks down. Empty or omitted = the default price tier.
  • integration_instance_ids (optional, array of integer sales channel integration instance ids): channels to push new prices to. Empty = every channel the products are listed on.
  • target_sell_out_on (optional, date Y-m-d or null): when the stock should be gone. Drives sell-through pacing, weeks left and the behind_plan / cover_exceeds_time_left triggers.
  • floor_type (required when sent): the lowest price the plan may suggest — landed_cost (never below landed cost), pct_of_original (never below floor_value % of the original price), none_from_step (landed cost until step floor_value, then no floor — liquidation).
  • floor_value (number 0–100 or null): required when floor_type is pct_of_original (the % of the original price) or none_from_step (the step number from which prices may go below cost).
  • auto_apply (optional, boolean, default false): apply due markdowns automatically instead of waiting for review. Held suggestions (floor or guardrail breaches) are never auto-applied.
  • reference_price_rule (required when sent): how the compare-at ("was") price is chosen — omnibus_30d (EU/UK: lowest price in the 30 days before the first reduction), us_bona_fide (US: the regular price, only when held for bona_fide_days), none (no compare-at price).
  • bona_fide_days (optional, integer 1–730, default 90): for us_bona_fide, how long the regular price must have been held.
  • merchandise_plan_id (optional, integer or null): a merchandise plan whose planned markdown value this plan's markdown cost feeds into.
  • steps (optional, array of 1–10 steps; replaces the whole ladder when sent): the markdown ladder, in order. Each step must discount more than the one before — prices never go up within a plan.
    • steps.*.discount_pct (required, number > 0 and < 100): % off the original (enrolment) price.
    • steps.*.trigger_type (required): what makes the step due — immediately (next daily run after the plan starts), on_date, behind_plan, cover_exceeds_time_left (weeks of cover at the 30-day sales rate is longer than the weeks left to target_sell_out_on), days_after_previous (not allowed on the first step).
    • steps.*.trigger_params (optional, object): parameters for the trigger.
      • steps.*.trigger_params.date (date Y-m-d): required for on_date.
      • steps.*.trigger_params.weeks (integer 0–104): required for behind_plan — compare sell-through after this many weeks.
      • steps.*.trigger_params.target_pct (number 0–100, optional): for behind_plan, the sell-through % to be at; omit to compare against a straight line to target_sell_out_on.
      • steps.*.trigger_params.days (integer 1–365): required for days_after_previous — days after the previous step was applied. When floor_type is not sent, the floor_value rule is checked against the plan's current floor type.

Response: data (the plan, single-plan form) and message.

Plan fields: id, name, status (active | ended), end_action (keep | restore, set once ended), ended_at, scope (how products were chosen: product_ids and/or filters, plus excluded_product_ids - products removed from the plan that its filter must not enrol again; absent when there are none), price_tier_ids, integration_instance_ids, target_sell_out_on (Y-m-d), floor_type + floor_type_label, floor_value, auto_apply, reference_price_rule + reference_price_rule_label, bona_fide_days, merchandise_plan_id, products_count, pending_suggestions_count (pending + held), created_by_user_id, created_at, updated_at. The single-plan form also returns: merchandise_plan (id, retail_period, planned_markdown_value, or null), steps (id, position, discount_pct, trigger_type, trigger_label, trigger_params), price_tiers (id, name — the tiers the plan prices; the default tier when none were chosen), integration_instances (id, name) and projected_markdown_value (the markdown cost of the open and applied suggestions, in the plan's currency).

Requires a Bearer token with the products read/write scope and the products.manage_pricing permission.

Request​

Responses​

OK

Response Headers
    Content-Type