Skip to main content

Create Clearance Plan

POST 

/api/v2/clearance-plans

Create a clearance plan, enrol its products and run the first evaluation straight away, so step-1 markdown suggestions are ready for review (or applied, with auto_apply).

Required scope: products:write

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

On enrolment each product's current price in every plan tier is saved as its original price, and its sell-through is measured from when it entered its current lifecycle state (or from now). A product already in another active plan, or with no price in the plan's tiers, is skipped and listed under enrolment.skipped. A plan whose scope is a filter re-runs that filter on every daily evaluation, so newly matching products join automatically.

Body:

  • name (required, string, max 120)
  • product_ids (array of up to 5000 distinct product ids): products to enrol. Send product_ids, filters, or both.
  • filters (object): a products-list filter payload, e.g. {"filter": {"lifecycle_state.is": "discontinued"}} — the same filter[...] / filter_groups parameters the product list accepts.
  • 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): 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): 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; omitted = the Standard 3-step ladder): 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.

Response: data (the plan, single-plan form), enrolment (added, skipped: product id => reason), evaluation (suggested, held, auto_applied, enrolled, push_warnings), message. HTTP 201. push_warnings lists channel pushes that did not happen for markdowns applied automatically (auto_apply), one "<channel>: <reason>" string each - the prices are saved and reach those channels on the next price push.

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​

Created

Response Headers
    Content-Type