Pricing & listing rules

Three prices travel with a listing, and the first two arm the vehicle's listing rules: the per-vehicle lines that answer buyer offers without waiting for a person.

The three prices

How an offer is answered

The events tell you which path an offer took: OFFERS.CREATED for every offer, immediately followed by OFFERS.ACCEPTED or OFFERS.DECLINED with "autoProcessed": true when a rule decided; an offer in your review band fires its outcome event only when you decide. OFFERS.ACCEPTED is also sent, without autoProcessed, when the seller accepts by hand, when the buyer accepts the seller's counter, and when an approved price change accepts an offer that now qualifies (see Webhooks).

A worked example

Your F-150 lists at $22,500 with floorPrice: 18000. Three offers arrive the first week:

Updating prices

PATCH /api/v1/listings/{id} (or a compat offering POST) applies immediately — to the vehicle and the live marketplace listing. Bulk repricing: PATCH /api/v1/listings/bulk with vins or listingIds, up to 500 per call.

Since 1.5.0 a price change goes through the same rules as one made in the app, on every one of these routes:

• No price moves under a live offer or a sale. While the vehicle is Under Offer, Offer Accepted, in Due Diligence, Ready to Deliver or Sold, its price is the one a deal was agreed against: a change answers 409 CONFLICT.
• A buy-now never sits below the floor, as it is or as the same request sets it: 403 BELOW_FLOOR. A buy-now on a vehicle with no floor answers 422 INVALID ("Set a floor price first"), since the price is measured against it.
• The floor is the seller's. An agent never sets it (403 PEOPLE_ONLY); an API key acts as your organization and may. An agent may set the buy-now (listing) price, here and through the app's actions (set_listing_prices, edit_vehicle), within these same rules: never below the floor, never while a live offer or a sale is open.

Nothing is written when a change is refused. On the bulk route each item is refused on its own, with its code, and the rest of the batch goes ahead. A single PATCH also takes ?dryRun=true and an Idempotency-Key. Before 1.5.0 these changes were written.

Every price change re-arms the lines to the prices as they now stand, and a vehicle priced by a pricing rule has its rule worked again from the new floor.

Floors for many vehicles at once

POST /api/v1/vehicles/floor-prices (set_floor_prices) sets the floor of up to 500 vehicles not yet on the market, in one of four modes: absolute (an amount), multiplier or fixed-delta (from each vehicle's latest retail valuation) and, since 1.9.0, wholesale-percent: the latest wholesale valuation plus value percent, so { "mode": "wholesale-percent", "value": 2 } sets each floor 2% over wholesale: Cypress's own floor default (since 1.10.0 the one every suggestion uses: the appraisal, the pricing insight and the vehicle form).

A floor is a promise, so it is only worked out from a valuation that is current: one older than the refresh window (30 days, the window in which Cypress does not pay for a new valuation) is skipped with code: "VALUATION_STALE" and its date, unless you send allowStale: true. Ask for a new valuation with revalue_vehicle first. A vehicle with no valuation is skipped with code: "NO_VALUATION". The answer lists floors (each vehicle's new floor, with the wholesale and its date) and skipped; ?dryRun=true works out every floor and writes nothing. Setting a floor is a person's act: an agent's token is refused 403 PEOPLE_ONLY.

Beyond per-vehicle rules

Cypress also runs org-level pricing rules (launch pricing computed from valuations) and an automation engine that can price and launch drafts for you; your API pushes then need nothing but the vehicle data.

Your organization's own rules are yours to manage, in Settings › Pricing rules or through the API: GET /api/v1/pricing-rules lists them with Cypress's global ones, POST /api/v1/pricing-rules creates one, and PATCH /api/v1/pricing-rules/{id} changes one of yours (since 1.9.0): switch it off with isActive: false, choose applyBehavior (AUTO applies the outcome at once, NOTIFY_CM suggests it to Cypress), or change its conditions and figures. A change is an admin's or a fleet manager's, never an agent's (403 PEOPLE_ONLY); it takes ?dryRun=true and an Idempotency-Key, is in your audit trail, and sends ORGANIZATION.UPDATED with change: "SETTINGS". Cypress's global rules are not yours to change (404). Vehicles a rule already priced keep their prices.

A rule lists a car only when it is ready

Since 1.10.0. When a rule's outcome is to approve and list a vehicle (apply_pricing_rule, apply_pricing_rules with confirm: true), the vehicle first passes the listing checklist the Launch button checks: its location state, mileage and condition (a grade or a score), with the rule's price as the asking price. Something missing, and nothing moves: the answer is an error naming it (The rule would list it, but it is missing what every listing needs: mileage, condition) and the vehicle stays in review. Before 1.10.0 a rule listed it anyway.

The bulk preview (?dryRun=true, or confirm left out) says it ahead: missing lists the checklist fields the vehicle lacks when the rule would list it, and every answer that lists carries the offer lines the rule sets, computedAutoAcceptAbove (offers at or above it are accepted) and computedAutoDenyBelow (offers below it are declined), as the single apply always did.