Skip to main content

End Season

POST 

/api/v2/seasons/:season/end

Move the season's selected candidates to Phasing out or Discontinued in a background job named "Ending season <code>". Each product's lifecycle change cascades to its variants and is recorded with the reason "seasonal end". When notify_customers is true, one discontinuation notice per buyer is queued after the job finishes.

Required scope: products:write

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

Use the preview call first to see the candidates and their impact.

Body (all optional):

  • to_state: phasing_out or discontinued (default: discontinued).
  • product_ids (array of integers): limit the change to these candidates. Ids that are not candidates of the season are ignored. Omit to include every candidate.
  • discontinue_on (date Y-m-d): required when to_state is phasing_out, and must be after today. Ignored for discontinued.
  • last_order_date (date Y-m-d): phasing_out only; must be on or before discontinue_on.
  • note (string, max 500): reason recorded on each product's lifecycle history (default: "Season <code> ended").
  • notify_customers (boolean, default false): after the change, email recent B2B buyers one discontinuation notice for the whole season. Needs the customers.send_communications permission and, for an API token, the customers:write scope; without them the request returns 403 ("You need the customers.send_communications permission to email customers. Untick that option or ask an admin for the permission." or "This API token is missing the customers:write scope needed to email customers.").

Returns 422 when no candidate is selected.

Response data: tracked_job_log_id (id of the background job's progress record), job_name, product_count (products queued for the change).

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

Request​

Responses​

OK

Response Headers
    Content-Type