Planning API (Buy planning)

With Buy planning switched on for your organization, your purchasing system can keep the buy plan in step with what it already knows: the quarter's goal and budget, the vehicles you are hunting (targets), what is on the market that fits them, and what you have bought, including purchases made somewhere else. Every write goes through the same rule the Buy plan page uses, so the API and the app can never disagree.

Nothing here makes an offer, or touches a seller. Buy planning is your plan; an offer on a listing goes through Remarketing, not this API.

"Planning" has two sides in this API. This page is Buy planning, the dealer's plan. Sell planning, the plan that hands vehicles to Sell, is the Planning API (Sell planning). They are separate products with separate scopes, and an organization can have either or both.

You only ever see your own organization's data. A key acts as your organization itself: there is no delegation, and the audit trail says API · and the key's name.

Scopes and the product switch

Every route needs an organization with Buy planning switched on. Without it, each one answers 403 BUY_PLANNING_NOT_ENABLED, reads included, and nothing is written. It is a switch of its own: Sell planning being on does not turn it on, nor the other way round. Then:

buy-planning:write implies buy-planning:read, and buy-planning:read (beside webhooks) is the scope that lets a key subscribe to the BUY.* webhooks. A key made without picking scopes never gets either. Tick Buy planning (read) or Buy planning (read and write) when you create the key on the Integrations page; the boxes are offered when your organization has Buy planning. GET /api/v1/organization tells you what the key can do: products.buyPlanning and the capabilities buy-planning.read and buy-planning.write. See Your organization and key.

Quick guide

Six steps, from a new key to an approved quarter. Every request carries your key as x-api-key; $BASE is https://staging.app.getcypress.ai while you build.

curl "$BASE/api/v1/organization" -H "x-api-key: $KEY"

{
  "products": {
    "remarketing": { "enabled": true },
    "planning": { "enabled": false, "requestedAt": null },
    "buyPlanning": { "enabled": true, "requestedAt": "2026-09-14T15:20:00.000Z" }
  },
  "capabilities": [
    { "capability": "buy-planning.read", "allowed": true },
    { "capability": "buy-planning.write", "allowed": true }
  ]
}

curl "$BASE/api/v1/buy-planning/quarters/current" -H "x-api-key: $KEY"

{
  "periodKey": "2026-Q4", "label": "Q4 2026", "start": "2026-10-01", "end": "2026-12-31", "closed": false,
  "unitsGoal": null, "budget": null, "mandate": null,
  "approval": null,
  "progress": { "bought": 0, "inClosing": 0, "spent": 0, "inClosingAmount": 0, "spentInPlan": 0, "spentOutsidePlan": 0 },
  "digest": "9c4e1a07b2d35f68"
}

curl -X PUT "$BASE/api/v1/buy-planning/quarters/current" \
  -H "x-api-key: $KEY" -H "content-type: application/json" \
  -d '{ "unitsGoal": 40, "budget": 900000, "mandate": "USUAL_MIX" }'

curl -X POST "$BASE/api/v1/buy-planning/targets" \
  -H "x-api-key: $KEY" -H "content-type: application/json" \
  -d '{
    "make": "Toyota", "model": "RAV4", "trims": ["XLE"],
    "yearMin": 2021, "yearMax": 2023, "mileageMax": 60000, "states": ["FL", "GA"],
    "quantity": 6, "needBy": "2026-11-27",
    "targetUnitPrice": 25000, "maxUnitPrice": 27000,
    "priority": 1, "track": "BALANCED"
  }'

{
  "id": "clx…", "label": "Toyota RAV4 XLE", "status": "OPEN", "displayStatus": "OPEN", "source": "MANUAL",
  "track": "BALANCED", "priority": 1,
  "make": "Toyota", "model": "RAV4", "trims": ["XLE"], "planningClass": null, "bodyClasses": [], "fuelTypes": [], "conditions": [],
  "yearMin": 2021, "yearMax": 2023, "mileageMin": null, "mileageMax": 60000, "states": ["FL", "GA"],
  "quantity": 6, "needFrom": null, "needBy": "2026-11-29", "needByWeek": "W48", "periodKey": "2026-Q4",
  "targetUnitPrice": 25000, "maxUnitPrice": 27000,
  "bought": 0, "inClosing": 0, "remaining": 6,
  "note": null, "createdAt": "2026-10-11T14:02:00.000Z", "updatedAt": "2026-10-11T14:02:00.000Z"
}

curl "$BASE/api/v1/buy-planning/targets/$TARGET_ID/matches" -H "x-api-key: $KEY"

{
  "targetId": "clx…", "track": "BALANCED", "totalCount": 2,
  "items": [
    {
      "vehicleId": "clx…", "url": "https://app.getcypress.ai/marketplace/clx…",
      "year": 2022, "make": "TOYOTA", "model": "RAV4", "trim": "XLE", "mileage": 31000, "state": "FL",
      "ask": 26400, "isNew": true, "score": 100, "kind": "EXACT", "misses": []
    },
    {
      "vehicleId": "clx…", "url": "https://app.getcypress.ai/marketplace/clx…",
      "year": 2022, "make": "TOYOTA", "model": "RAV4", "trim": "LE", "mileage": 38200, "state": "GA",
      "ask": 24900, "isNew": false, "score": 92, "kind": "NEAR", "misses": ["Trim LE, not XLE"]
    }
  ]
}

curl -X POST "$BASE/api/v1/buy-planning/purchases" \
  -H "x-api-key: $KEY" -H "content-type: application/json" \
  -d '{
    "targetId": "clx…", "purchasedAt": "2026-10-09", "unitPrice": 24000,
    "description": { "year": 2022, "make": "Toyota", "model": "RAV4", "vin": "2T3W1RFV0NW000001", "mileage": 31000 },
    "note": "Bought at the Orlando auction"
  }'

{
  "id": "clx…", "state": "FILLED", "source": "RECORDED", "targetId": "clx…", "targetLabel": "Toyota RAV4 XLE",
  "unitPrice": 24000, "purchasedAt": "2026-10-09T00:00:00.000Z", "periodKey": "2026-Q4",
  "vehicle": { "id": null, "label": "2022 Toyota RAV4" }, "note": "Bought at the Orlando auction"
}

curl -X POST "$BASE/api/v1/buy-planning/quarters/current/approve" \
  -H "x-api-key: $KEY" -H "content-type: application/json" \
  -d '{ "digest": "3b7d0c91e5a8f204" }'

{
  "periodKey": "2026-Q4", "label": "Q4 2026", "start": "2026-10-01", "end": "2026-12-31", "closed": false,
  "unitsGoal": 40, "budget": 900000, "mandate": "USUAL_MIX",
  "approval": { "approvedAt": "2026-10-11T14:09:00.000Z", "changesSince": [] },
  "progress": { "bought": 1, "inClosing": 0, "spent": 24000, "inClosingAmount": 0, "spentInPlan": 24000, "spentOutsidePlan": 0 },
  "digest": "3b7d0c91e5a8f204"
}

The routes

All under /api/v1/buy-planning. Dates are ISO strings, and money is a number in US dollars. Every write takes ?dryRun=true (the same checks and refusals, { "dryRun": true, "changes": … }, nothing written) and an Idempotency-Key (a retry answers the same, once). Since 1.5.0.

Another organization's id is 404, exactly like an id that does not exist.

The quarter

The PUT takes no note: the note on a quarter is the dealer's, and a key never clears it.

The plan's quarter

GET /plan (MCP: get_buy_plan) carries the quarter as the Buy plan page shows it, in quarter. Its money comes from the same computation as the page and progress above, so the three never disagree:

Changed in 1.9.0: quarter.spent used to add the closings in progress, so it read higher than the page's "spent". That figure is spentOrInClosing now.

Targets

The fields of a target have the names of the body you POST, so a target you read can be edited and sent back to PATCH: the fields that are only read (id, displayStatus, needByWeek, periodKey, bought, inClosing, remaining, createdAt, updatedAt) are ignored. A whole-body PATCH replaces the editable fields, as the app's edit does.

Matches

Each match carries the listing's public facts: vehicleId, a public Marketplace url, year, make, model, trim, mileage, state and the public ask (null when the listing shows none). Beside them: score (100 is exact), kind (EXACT or NEAR), isNew (first seen in the last three days) and misses, what a near match is not, in plain words. The list is in the app's order: exact first, then by score; within a score, new ones first, then by ask.

A target finds the listings that fit it at its track's floor (80, 90 or exact only), without those of your own organization and the ones you hid. Demo and real organizations are two worlds: a listing reaches a dealer of its own world only.

Purchases

A purchase from a Cypress closing follows its closing: it cannot be removed here (409 FROM_CLOSING).

Closed quarters

A quarter whose last day has passed is history, and its plan no longer changes, over the API as in the app. A quarter is over from the first instant after its last day, UTC. closed on the quarter says it, and a target says which quarter it counts in with periodKey.

What answers 409 QUARTER_CLOSED, with nothing written:

{
  "error": "This quarter is closed. A closed quarter is history, so its plan no longer changes.",
  "code": "QUARTER_CLOSED"
}

It is not retryable: waiting does not reopen a quarter. Add the target to a week of a quarter in progress instead. error is one fixed sentence: switch on code.

Purchases are never refused for a closed quarter. A purchase is a fact: it happened. Record one late, against a target of a closed quarter too; move one to a target of a closed quarter; remove one you recorded. A late sync from your purchasing system is natural.

The approval keeps its own codes, as in the app: approving a quarter that is over answers 409 PERIOD_CLOSED. Hiding a match is not a change to the plan, so a closed quarter does not refuse it either.

Approval refusals

POST /quarters/{periodKey}/approve answers 409 with one of three codes. The messages are fixed text; nothing you sent is echoed back.

What the matches never carry

A match is a listing's public face, and that is all of it, in the reads and in the BUY.TARGET.MATCHED webhook alike. It never carries a seller's name or id, a seller's floor, thresholds or limits, a VIN, or the Cypress staff view that fits a seller's limits to your target. That fit is staff-only and has no door here: a key is a dealer. Planned supply from other sellers reaches you in the app only as an anonymous count, and only when at least two sellers plan it. Your own targets and prices are never shown to a seller either.

Sequoia's draft

Since 1.5.0 the app's Plan my quarter is on the API. POST /drafts answers the starting plan the wizard shows: a unitsGoal, a budget, and three to eight targets, each with its spec, quantity, needBy, prices, track and why, read from your purchases and the market (basis says which, words says it in plain words). Nothing is written.

Keep it with POST /drafts/apply: send the quarter's periodKey, mandate, unitsGoal and budget, and the targets you keep, changed or not (each with the draft's key). A target you add yourself carries "origin": "DEALER". The answer is 201 with the targets made, in the shape of GET /targets. A kept target needed in a quarter that is over answers 409 QUARTER_CLOSED and nothing is written; a target that does not validate answers 422 with issues naming it (targets.2.make). With ?dryRun=true it is all written in a transaction that is rolled back: the same refusals, and { "dryRun": true, "changes": … } with the targets it would keep (without ids). An Idempotency-Key makes a retry safe.

Approving is a person's. "approve": true approves the quarter in the same step for an API key or an app acting for a person. An agent's token that sends it answers 403 PEOPLE_ONLY and nothing is written: an agent keeps the draft, and a person approves the quarter. The same holds for POST /quarters/{periodKey}/approve.

What stays in the app

Sequoia's rail, the forecast (the next weeks), the Market board and the Cypress desk are the app's. So are the Buy at the ask offers: an offer on a listing goes through Remarketing, not this API. How Buy planning works is in the Planning manual: Buy planning.

Webhooks

Your purchasing system does not have to poll. Six events tell it when the plan moves, each with the same target and match objects the reads above return:

To receive them, register a subscription that lists the events. They are opt-in (a subscription without an eventTypes filter never receives them), Cypress dialect only, and they need the buy-planning:read scope beside webhooks, on an organization with Buy planning:

curl -X POST "$BASE/api/v1/webhooks/subscriptions" \
  -H "x-api-key: $KEY" -H "content-type: application/json" \
  -d '{
    "callback": "https://purchasing.example.com/cypress",
    "eventTypes": ["BUY.TARGET.MATCHED", "BUY.TARGET.FILLED", "BUY.TARGET.ENDED"]
  }'

A key without the scope gets 403 SCOPE_MISSING; an organization without Buy planning, 403 BUY_PLANNING_NOT_ENABLED; a subscription that would use the Manheim names, 422. A new match arrives like this:

{
  "href": "https://app.getcypress.ai/api/v1/buy-planning/targets/clx…/matches",
  "eventType": "BUY.TARGET.MATCHED",
  "resource": "buy",
  "body": {
    "target": { "id": "clx…", "label": "Toyota RAV4 XLE", "periodKey": "2026-Q4" },
    "match": {
      "vehicleId": "clx…", "url": "https://app.getcypress.ai/marketplace/clx…",
      "year": 2022, "make": "TOYOTA", "model": "RAV4", "trim": "XLE", "mileage": 31000, "state": "FL",
      "ask": 26400, "isNew": true, "score": 100, "kind": "EXACT", "misses": []
    }
  },
  "createdOn": "2026-10-11T14:00:03.120Z",
  "relatedResources": []
}

Each event is delivered to an endpoint once, however many times its cause is noticed, and the body is the moment it happened (read href for the target as it is now). The envelope, the signature, the retries, a body example for each event and the rules for subscribing are in Webhooks.