Vehicle lifecycle
What happens to a vehicle from the moment you push it to the moment it sells.
TL;DRAI summary
This chapter explains the stages a vehicle goes through on Cypress, from when it's added to when it's sold or archived, and its life stage — Operation, Planning, Remarketing, Post-sale or Retired. It covers which vehicles the API shows by default, and how a vehicle crosses from Planning into Sell only through its plan.
Every vehicle on Cypress moves through one lifecycle, whether it arrived through the API, a CSV import, or the app. Understanding it explains every status you will see in API responses and events.
The lifecycle
Why draft-first
A bad push can never publish a malformed listing. Drafts cost nothing, are
freely deletable (except planning stock), and give Cypress review (or your
automation rules) the chance to complete photos, condition and valuation
before a buyer ever sees the car. When you trust a payload end-to-end,
listingMode: IMMEDIATE skips the wait.
Pre-listing
An API-pushed vehicle lands as DRAFT — the draft-first rule: a bad push can never publish a malformed listing. From there:
- Review — Cypress ops (or the org's own team) completes the record: photos, condition, valuation.
- Approval — the vehicle becomes
APPROVED, the launch-ready state. - Launch — review, an automation rule, or your API call
(
listingMode: IMMEDIATE) publishes it. Launch is atomic: the listing goes live, pricing rules arm, and buyers can act.
Listed
LISTED is the selling state — visible on the vehicle's
sales channels. ON_HOLD is its paused twin: off
market, everything intact, one call to resume.
The deal
A buyer's offer moves the vehicle to UNDER_OFFER. Acceptance
(OFFER_ACCEPTED) opens the closing process —
due diligence, documents, payment, delivery — ending in SOLD.
How API listings map to lifecycle statuses
Your listing (or Manheim-dialect offering) tracks the vehicle:
| Listing status | Meaning | Typical vehicle status |
|---|---|---|
REQUESTED | Pushed, not yet launched | DRAFT → APPROVED |
ACTIVE | Live on its channels | LISTED, UNDER_OFFER |
PAUSED | Temporarily off market | ON_HOLD |
SOLD | Sale completed on Cypress | SOLD |
NOT_SOLD | Taken off market without a sale | ARCHIVED |
CANCELLED | You cancelled it | ARCHIVED (restorable) |
Life stage (API 1.1.0)
Every vehicle now carries lifeStage: OPERATION, PLANNING, REMARKETING, POST_SALE or RETIRED.
The integrations API works on Sell stock — REMARKETING, POST_SALE, RETIRED.
Behavior change in 1.1.0
Vehicles your organization keeps in Operation or Planning (for example, loaded with the planning import)
no longer appear in GET /api/v1/vehicles or GET /api/compatible/v1/units/mine, and reading one by id
answers 404. Every refusal on such a vehicle — updates and re-pushes by VIN
(including PATCH, PUT, ?mode=upsert, and each item of vehicles/bulk /
units/bulk), prices, listings, deletion, and sold-elsewhere — answers 409
with "code": "PLANNING_STOCK". A POST /vehicles for a VIN already in
Planning also answers 409 PLANNING_STOCK — it no longer returns the
existing vehicle's id the way a duplicate-VIN 409 does. The vehicle
appears on its own once its sale window hands it to Sell. A listing left
open on a vehicle later demoted back to Planning stays readable and
cancellable (GET/DELETE on /listings, /offerings/mine); any other
update to it answers 409 PLANNING_STOCK too. See
Reading planning stock below — that arrived
in 1.2.0.
Reading planning stock (1.2.0)
A key holding the planning:read scope, for an organization with Planning
switched on, can list and read planning stock:
GET /api/v1/vehicles?lifeStage=OPERATION,PLANNING. Reading a single one by
id works the same way — GET /api/v1/vehicles/{id} shows it to a
planning:read key and answers 404 to any other key, exactly as before.
Sell writes to planning stock (a PUT, a re-push, prices, listings,
deletion, sold-elsewhere) still answer 409 PLANNING_STOCK; planning
writes go through the Planning API (below). With Planning
switched off for the organization, planning stock answers
403 PLANNING_NOT_ENABLED instead — it is frozen, not merely waiting for a
sale window. See Your organization and key
for the planning:read/planning:write scopes, and
Errors for every code.
Planning over the API (1.3.0)
A planning:write key can push vehicles straight into Operation or
Planning (lifeStage: OPERATION or PLANNING on POST /api/v1/vehicles),
keep them current (PATCH, ownership, odometer readings, cost events,
departures) and drive the plan — sale windows, the bench, blockers, and the
hand-off that moves a window's vehicles into Sell as drafts. A vehicle
crosses the Planning/Sell line only through the plan: the hand-off
(cohort confirm) or a demotion — never by a push or a PATCH. See the
Planning API.
CRM
Read and write your organization's own CRM book, its contacts, businesses and deals, from your systems or an agent, without ever seeing another organization's.
Planning API (Sell planning)
Push your fleet into Sell planning, keep it current, read the plan, drive it and plan the quarter — the same rules the app uses, since API 1.3.0. Closed quarters since 1.4.0; the strategy, goals, the quarter's approval and Sequoia's schedule since 1.5.0.