ConnectWise CPQ API Patterns

ConnectWise CPQ MCP Tools & API Patterns

Overview

ConnectWise CPQ (formerly ConnectWise Sell, originally Quosal) is the quoting and proposal tool in the ConnectWise stack. The REST API is deliberately small and quote-centric: 19 paths / 29 operations covering quotes, their line items, tabs, customers and payment terms, plus a handful of lookup lists. The MCP server exposes it as 25 flat tools, all prefixed cpq_.

CPQ is not ConnectWise PSA. It has its own host, its own auth scheme (no clientId), and a much narrower surface — pair it with the connectwise-psa plugin when a workflow needs opportunities, products, or agreements.

Anti-triggers

"ConnectWise" brands three products with three unrelated APIs, and their credentials are not interchangeable. PSA's and CPQ's Basic tokens are the trap: both are base64(<something>+<publicKey>:<privateKey>), so a company ID and an access key look identical in the same slot. Authenticating against the wrong product fails as a 401 — or a 500 when a header is absent entirely — which reads like a permissions problem on an account that is in fact fine.

• ConnectWise PSA (Manage) — regional api-{na,eu,au}.myconnectwise.net hosts, a companyId in the Basic string, and a mandatory clientId header CPQ does not use. Use connectwise-psa-api-patterns.
• ConnectWise Automate — on-premise RMM server, /cwa/api/v1/ base path, Bearer-token auth, singular condition= filters. Use connectwise-automate-api-patterns.

Connection & Authentication

Upstream CPQ uses HTTP Basic with a three-part credential:

username = <accessKey>+<publicKey>      # note the literal "+" between them
password = <privateKey>
Authorization: Basic base64(<accessKey>+<publicKey>:<privateKey>)

Requirements: CPQ 2022.2 or newer, and the CPQ user owning the key pair must be flagged as an API user (isApiUser on the user record). A non-API user's keys authenticate as nobody and every call fails.

Through the WYRE MCP gateway the three credentials are supplied as gateway fields and arrive at the MCP server as headers — the server builds the Basic token itself:

If any of the three headers is missing the server answers 401 (JSON-RPC error -32001) before the tool runs; it never falls back to server-side environment credentials. Running the server directly instead of through the gateway, the same values come from CPQ_ACCESS_KEY, CPQ_PUBLIC_KEY, and CPQ_PRIVATE_KEY.

Two things that trip people coming from ConnectWise PSA/Manage:

• No clientId header. CPQ's spec defines Basic auth only. Sending Manage-style client registration headers is harmless but pointless — do not copy Manage auth code.
• Content type carries a version parameter: Content-Type: application/json; version=1.0 on every request, mirroring Manage's media-type versioning.

Verify a connection with cpq_test_connection, which performs the cheapest authenticated read (the user list) and reports who the API user is.

Base URL

https://sellapi.quosalsell.com

One global host — there are no regional variants (api-eu, api-au, staging) the way Manage has them. Tenancy is carried by the access key, not the hostname. The base URL is overridable only if ConnectWise support tells you to change it.

Paths are not uniformly prefixed: entity endpoints live under /api/..., but users live under /settings/user.

Tool Surface

25 flat tools, no router. Reads first, then writes.

See references/api.md for the underlying REST endpoint catalog.

Filtering with conditions

List tools take a Manage-style condition string. The syntax is unforgiving about literal formatting:

Operators: = != < <= > >= contains like in not in. Combine with AND / OR, parentheses allowed. Nested fields use a slash: customer/accountName.

conditions: isArchive = False AND createDate >= [2026-07-01]
conditions: idQuote = "3f1c8d2e-1b44-4a90-9f6a-1d0f2e5b7c11"

Called with no conditions, cpq_search_quotes asks for a created-since date and, if the client cannot answer, defaults to the last 90 days and says so in the result.

Field Selection

includeFields is a comma-separated allowlist and is worth using on nearly every call — QuoteView carries ~204 properties (60+ of them empty zCustom* custom-field slots), QuoteItemView ~224, QuoteTabView ~175.

includeFields: id,name,quoteNumber,quoteVersion,quoteStatus,quoteTotal

Pagination

page is 1-based; pageSize maxes out at 1000. Responses are bare JSON arrays — no envelope, no total count, no next-page link.

Walk pages until a page returns fewer rows than pageSize. The MCP tools wrap results as { count, quotes } (or items, terms, ...) — that count is the length of the current page, never a collection total, so never treat it as "how many exist".

showAllVersions: true on the quote, quote-item and quote-tab searches includes superseded quote versions; the default returns latest versions only.

Updates Are JSON Patch

Every update endpoint takes an RFC 6902 patch array, not a merge-patch object. Sending {"name": "..."} where an array of ops is expected fails.

The update tools accept either shape and build the ops for you:

• fields — a partial object; each entry becomes a replace op
• patch — raw RFC 6902 ops, when you need add, remove, move, copy, or test

Pass one or the other, never both, and never an empty one.

fields: { "name": "Acme — Managed Services FY27", "expirationDate": "2026-09-30T00:00:00Z" }
patch:  [{ "op": "replace", "path": "/name", "value": "Acme — Managed Services FY27" }]

Quote customers are the sole resource that also accepts a full-replace PUT upstream; the MCP surface exposes only the patch path.

Errors

Error bodies carry a single message key with no error code and no field-level detail. Successful writes return the entity; DELETE returns 204 No Content.

Rate limits are undocumented for CPQ and no Retry-After has been observed. Treat 429, 502, 503 and 504 as retryable with exponential backoff and keep concurrency modest.

What CPQ's API Does Not Have

Confirmed absent from the official spec — do not go looking for these tools, and route the workflow elsewhere:

Related Skills

• ConnectWise CPQ Quotes — the quote lifecycle, versions, customers, terms
• ConnectWise CPQ Quote Items — line items, tabs, and pricing fields