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).
products:writeGrant 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
- 200
- 401
- 403
- 404
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not Found
Response Headers
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.