Skip to content

Integrate with the Sales Quote Lifecycle

Use this guide when a portal, middleware service, or other downstream system needs to react to a Sales Quote progressing through Velosity. It defines the boundary between the Velosity lifecycle and tenant-specific workflow labels.

Contract at a glance

Concern Contract
Lifecycle authority Velosity Sales Quote status
Standard lifecycle DRAFT > OFFERED > ACCEPTED > RELEASED
Sales Order creation A Sales Order exists only when the quote is RELEASED.
Tenant workflow labels Sales Quote phases are optional and tenant-defined.
Payment webhook Subscribe to Sales Quote — Payment Changed when a downstream process needs completed-payment handling.
Lifecycle webhook Subscribe to Sales Quote — Status Changed.
Tenant-label webhook Subscribe to Sales Quote — Phase Changed only when local phase behavior is explicitly required.

In the standard release mode, a Draft quote with at least one line item is offered and accepted before it is released. With Incremental Release enabled, a Draft quote with a line item can be released directly. In either mode, do not assume that an Offered, Accepted, or phase-changed quote has a linked Sales Order.

Configure the webhooks

  1. In Velosity, create a webhook for the Sales Quote entity.
  2. Select Status Changed for any integration behavior tied to the lifecycle, portal eligibility, or Sales Order availability.
  3. Add Payment Changed if the receiver must react when payment is paid or otherwise changes state.
  4. Add Phase Changed only if the receiver deliberately implements the tenant's local phase definitions.
  5. Configure a public HTTPS endpoint, save the webhook, and use its test and delivery logs to verify the receiver.

See Webhooks for the common endpoint and delivery setup.

When events fire

Event Fires when Receiver action
Sales Quote — Payment Changed The quote's payment state changes. Read the delivered payment state and act only when it is the agreed terminal state, such as Paid.
Sales Quote — Status Changed A Sales Quote status has changed. Read the delivered quote's status and apply lifecycle-specific behavior. For RELEASED, the linked Sales Order may be retrieved or synchronized.
Sales Quote — Phase Changed A user changes the quote's tenant-defined phase. Use only for the agreed tenant-specific label behavior. Do not assume a Sales Order exists.

Phase-delivery behavior

A phase update can produce more than one delivery. Velosity queues a Phase Changed delivery as the phase update is recorded, then queues a second Phase Changed delivery after the update path completes. The first delivery can contain the quote's previous phase. If the selected phase has an associated status and that transition is valid, Velosity queues a Status Changed delivery between those two phase deliveries.

Consequently, receivers must not rely on delivery order or treat every Phase Changed delivery as the final quote state. A receiver that needs the lifecycle decision must use the status in the Status Changed delivery. A receiver that needs the final phase must tolerate duplicate and stale phase snapshots, or retrieve the quote after it has durably accepted the notification.

Payload

Velosity POSTs a Sales Quote representation as JSON. The body is the quote, not a Sales Order event envelope. For a Status Changed delivery, use the delivered status for lifecycle behavior. A Phase Changed delivery can contain a pre-update phase snapshot, as described above.

For customer-master synchronization, use the separate Customer / Created webhook described in Webhooks. Configure the receiving ERP to upsert that customer by customerID; a status or payment webhook can then associate the quote with the ERP customer. Do not depend on delivery order between the two webhook types.

The following abbreviated example shows the fields a lifecycle receiver should use; actual deliveries include the rest of the Sales Quote representation.

{
  "instanceID": "ABC",
  "salesQuoteID": "AB194631-130F-4EA2-A7C9-345B2959C120",
  "number": "SQ1000",
  "status": "OFFERED",
  "phase": "CUSTOMER REVIEW"
}

Treat the delivered document as a snapshot. Its phase can be absent or differ among tenants, and phase names are not stable integration identifiers. Persist the identifiers and current status needed for processing instead of using the display number or a phase label as the key.

Receiving responsibilities

Your receiving system owns its portal and downstream behavior. Velosity owns the quote status and the creation of the Sales Order on release.

  • Accept the POST durably before returning a successful response.
  • Process deliveries idempotently, using the tenant and quote identifiers plus the received state to recognize repeats and stale phase snapshots.
  • Make status-driven behavior depend on status, not phase.
  • Before reading or uploading a Sales Order, confirm that the quote is RELEASED and handle the case where no linked order is available.
  • Log and retry transient processing failures without asking Velosity to replay already accepted deliveries.
  • Reconcile failed deliveries from Velosity webhook logs and the receiving system's own logs.

For example, a portal upload triggered by a phase change on a Draft repair quote must not fail merely because no Sales Order exists. It should either wait for a RELEASED Status Changed event or perform only work that is valid for the current quote status.

Administration and release mode

The instance administrator selects Standard or Incremental Release in Setup > Settings under Sales Quotes. Release mode changes the permitted path to RELEASED, but it does not change the integration rule: RELEASED is the status at which a linked Sales Order is created. See CPQ Settings and Convert a Sales Quote to a Sales Order.