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.
products:writeGrant 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_communicationspermission and, for an API token, thecustomers:writescope; 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
- 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
Response Headers
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.