API reference
POST /v1/deals/{id}/stage
Move a deal to another stage
Move a deal to another stage
Applies the transition through the deal state machine (required fields, automatic tasks, client notifications and the stage_changed event for webhooks). A blocked transition is 409 transition_blocked with missing[]. With dry_run=true nothing is changed and the response says what is missing and shows the client message preview. Supports Idempotency-Key. The key acts with the manager role: stages reserved for other roles (e.g. accountant, logistics) are blocked. Requires scope write:deals.
- Authentication: header
Authorization: Bearer rv_live_...(API keys and scopes) - Required scope:
write:deals
Descriptions of the operation, parameters and fields come from the OpenAPI specification (
openapi.json).Parameters
| Field | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | Resource id (UUID). |
dry_run | query | "true" | "false" | no | true: do not change anything, return what is missing and the client message preview (always 200). |
idempotency-key | header | string | no | Makes a retry of this POST safe for 24 hours: the same key and body returns the stored response (Idempotent-Replay: true). |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
note | string | null | no | |
fields | object | no | |
fields.vehicle | object | no | |
fields.vehicle.vin | string | null | no | |
fields.vehicle.make | string | null | no | |
fields.vehicle.model | string | null | no | |
fields.vehicle.trim | string | null | no | |
fields.vehicle.year | integer | null | no | |
fields.vehicle.body | "sedan" | "hatchback" | "wagon" | "suv" | "crossover" | "coupe" | "convertible" | "minivan" | "van" | "pickup" | "truck" | "motorcycle" | "other" | null | no | |
fields.vehicle.fuel | "petrol" | "diesel" | "hybrid" | "phev" | "ev" | "lpg" | "cng" | "hydrogen" | "other" | null | no | |
fields.vehicle.engine | string | null | no | |
fields.vehicle.engineCc | integer | null | no | |
fields.vehicle.powerKw | integer | null | no | |
fields.vehicle.gearbox | "manual" | "automatic" | "cvt" | "robot" | "other" | null | no | |
fields.vehicle.mileageKm | integer | null | no | |
fields.vehicle.color | string | null | no | |
fields.vehicle.source | string | no | |
fields.vehicle.sourceUrl | string | null (uri) | no | |
fields.vehicle.lotId | string | null | no | |
fields.vehicle.titleStatus | "clean" | "salvage" | "rebuilt" | "flood" | "junk" | "parts_only" | "certificate" | "unknown" | null | no | |
fields.items | object[] | no | |
fields.items[].id | string (uuid) | no | |
fields.items[].kind | "lot_price" | "auction_fee" | "broker_fee" | "inland_us" | "ocean" | "port" | "inland_eu" | "customs_duty" | "excise" | "vat" | "broker_customs" | "certification" | "pension_fund" | "registration" | "repair" | "detailing" | "insurance" | "our_fee" | "other" | no | |
fields.items[].label | string | null | no | |
fields.items[].planned | number | string | null | no | |
fields.items[].actual | number | string | null | no | |
fields.items[].currency | "UAH" | "USD" | "EUR" | "PLN" | "GEL" | no | |
fields.items[].paidBy | "client" | "company" | no | |
fields.items[].paidAt | string | null (date-time) | no | |
fields.items[].documentId | string | null (uuid) | no | |
fields.items[].note | string | null | no | |
fields.items[].sort | integer | no | |
fields.shipment | object | no | |
fields.shipment.mode | "container" | "roro" | "truck" | no | |
fields.shipment.carrier | string | null | no | |
fields.shipment.containerNo | string | null | no | |
fields.shipment.billOfLading | string | null | no | |
fields.shipment.bookingNo | string | null | no | |
fields.shipment.vessel | string | null | no | |
fields.shipment.voyage | string | null | no | |
fields.shipment.portFrom | string | null | no | |
fields.shipment.portTo | string | null | no | |
fields.shipment.warehouse | string | null | no | |
fields.shipment.etd | string | null (date-time) | no | |
fields.shipment.eta | string | null (date-time) | no | |
fields.shipment.atd | string | null (date-time) | no | |
fields.shipment.ata | string | null (date-time) | no | |
fields.shipment.pickupAt | string | null (date-time) | no | |
fields.shipment.deliveredAt | string | null (date-time) | no | |
fields.shipment.status | "planned" | "booked" | "loaded" | "in_transit" | "at_port" | "discharged" | "released" | "delivered" | no | |
fields.customs | object | no | |
fields.customs.status | "draft" | "documents_sent" | "declared" | "paid" | "cleared" | "rejected" | no | |
fields.customs.declarant | string | null | no | |
fields.customs.declarationNo | string | null | no | |
fields.customs.duty | number | string | null | no | |
fields.customs.excise | number | string | null | no | |
fields.customs.vat | number | string | null | no | |
fields.customs.pensionFund | number | string | null | no | |
fields.customs.currency | "UAH" | "USD" | "EUR" | "PLN" | "GEL" | no | |
fields.customs.paidAt | string | null (date-time) | no | |
fields.customs.clearedAt | string | null (date-time) | no | |
fields.customs.notes | string | null | no | |
fields.etaDelivery | string | null (date-time) | no | |
fields.route | "sea" | "land" | no | |
fields.destinationCountry | string | null | no | |
fields.destinationCity | string | null | no | |
fields.lostReason | string | null | no | |
attachments | string (uuid)[] | no | |
notifyClient | boolean | no | |
messageOverride | string | null | no | |
channel | "telegram" | "viber" | "email" | "sms" | "webhook" | "in_app" | no | |
to | "lead" | "consult" | "contract_signed" | "deposit_paid" | "searching" | "bid_approved" | "won" | "paid_to_auction" | "pickup_scheduled" | "at_us_warehouse" | "loaded" | "in_transit_sea" | "at_eu_port" | "inland_to_border" | "customs_clearing" | "customs_cleared" | "certification" | "registration" | "ready_for_handover" | "handed_over" | "closed" | "lost" | "cancelled" | "on_hold" | "dispute" | yes | Target stage. |
Responses
200
The transition was applied (or previewed with dry_run).
application/json · Schema: StageResult
| Field | Type | Required | Description |
|---|---|---|---|
dryRun | boolean | yes | |
applied | boolean | yes | true: the deal was moved. false only for dry_run. |
from | "lead" | "consult" | "contract_signed" | "deposit_paid" | "searching" | "bid_approved" | "won" | "paid_to_auction" | "pickup_scheduled" | "at_us_warehouse" | "loaded" | "in_transit_sea" | "at_eu_port" | "inland_to_border" | "customs_clearing" | "customs_cleared" | "certification" | "registration" | "ready_for_handover" | "handed_over" | "closed" | "lost" | "cancelled" | "on_hold" | "dispute" | yes | |
to | "lead" | "consult" | "contract_signed" | "deposit_paid" | "searching" | "bid_approved" | "won" | "paid_to_auction" | "pickup_scheduled" | "at_us_warehouse" | "loaded" | "in_transit_sea" | "at_eu_port" | "inland_to_border" | "customs_clearing" | "customs_cleared" | "certification" | "registration" | "ready_for_handover" | "handed_over" | "closed" | "lost" | "cancelled" | "on_hold" | "dispute" | yes | |
ok | boolean | yes | The transition is possible (always true when applied). |
kind | string | null | yes | |
skipped | "lead" | "consult" | "contract_signed" | "deposit_paid" | "searching" | "bid_approved" | "won" | "paid_to_auction" | "pickup_scheduled" | "at_us_warehouse" | "loaded" | "in_transit_sea" | "at_eu_port" | "inland_to_border" | "customs_clearing" | "customs_cleared" | "certification" | "registration" | "ready_for_handover" | "handed_over" | "closed" | "lost" | "cancelled" | "on_hold" | "dispute"[] | yes | Stages skipped on the way (e.g. sea stages for a land route). |
missing | string[] | yes | |
reasonKey | string | null | yes | |
reasonRequired | boolean | yes | |
notifications | object[] | yes | |
notifications[].event | string | no | |
notifications[].to | string | no | |
taskIds | string (uuid)[] | yes | |
clientMessage | object | yes | Preview of the message the client gets (dry_run only). |
clientMessage.channel | string | yes | |
clientMessage.locale | string | yes | |
clientMessage.title | string | null | yes | |
clientMessage.text | string | yes | |
clientMessage.warnings | string[] | yes | |
deal | object | yes | The updated deal (null for dry_run). |
deal.id | string (uuid) | yes | |
deal.number | string | yes | |
deal.status | "lead" | "consult" | "contract_signed" | "deposit_paid" | "searching" | "bid_approved" | "won" | "paid_to_auction" | "pickup_scheduled" | "at_us_warehouse" | "loaded" | "in_transit_sea" | "at_eu_port" | "inland_to_border" | "customs_clearing" | "customs_cleared" | "certification" | "registration" | "ready_for_handover" | "handed_over" | "closed" | "lost" | "cancelled" | "on_hold" | "dispute" | yes | |
deal.pausedFrom | "lead" | "consult" | "contract_signed" | "deposit_paid" | "searching" | "bid_approved" | "won" | "paid_to_auction" | "pickup_scheduled" | "at_us_warehouse" | "loaded" | "in_transit_sea" | "at_eu_port" | "inland_to_border" | "customs_clearing" | "customs_cleared" | "certification" | "registration" | "ready_for_handover" | "handed_over" | "closed" | "lost" | "cancelled" | "on_hold" | "dispute" | null | yes | |
deal.type | "full_service" | "auction_only" | "logistics_only" | "resale" | yes | |
deal.route | "sea" | "land" | yes | |
deal.currency | "UAH" | "USD" | "EUR" | "PLN" | "GEL" | yes | |
deal.contactId | string (uuid) | yes | |
deal.managerId | string | null (uuid) | yes | |
deal.vehicleId | string | null (uuid) | yes | |
deal.destinationCountry | string | null | yes | |
deal.destinationCity | string | null | yes | |
deal.etaDelivery | string | null | yes | ISO 8601 date-time (UTC). |
deal.stageDates | object | yes | stage -> time of entering it. |
deal.trackingToken | string (uuid) | yes | Token of the public tracking page (Track). |
deal.trackingEnabled | boolean | yes | |
deal.lostReason | string | null | yes | |
deal.closedAt | string | null | yes | ISO 8601 date-time (UTC). |
deal.createdAt | string | yes | ISO 8601 date-time (UTC). |
deal.updatedAt | string | yes | ISO 8601 date-time (UTC). |
400
Invalid request parameters or body (code validation_error).
application/problem+json · Schema: Problem
401
Missing, malformed, unknown, revoked or expired API key (code unauthorized).
application/problem+json · Schema: Problem
403
The API key lacks the scope required by this endpoint (code insufficient_scope).
application/problem+json · Schema: Problem
404
No such deal in this tenant.
application/problem+json · Schema: Problem
409
Conflict: duplicate contact (duplicate_ids), a request with this Idempotency-Key is still being processed, or the stage transition is blocked (missing[]).
application/problem+json · Schema: Problem
422
Well-formed but not acceptable data (unprocessable_input), or Idempotency-Key reused with a different request.
application/problem+json · Schema: Problem
429
Rate limit exceeded for the tenant plan (code rate_limited). Wait Retry-After seconds.
application/problem+json · Schema: Problem