Skip to main content
Glama

QuBe Sync: QuickBooks Desktop API for developers

Update price level

update_price_level
Read-onlyIdempotent

Modifies a price level. The currency_ref should only be used with “per item” price levels.

The price_level_mod wrapper from qbXML is also accepted. Returns the v2 request to send, and the webhook payload QuickBooks' answer arrives in (this operation's response_json: its data shape and the status codes to handle).

Possible errors (error.code / error.type; the call result explains each): 1030 unsupported_request, 3000 invalid_object_id, 3040 invalid_amount, 3070 string_too_long, 3100 name_in_use, 3120 object_not_found, 3140 invalid_reference, 3150 missing_element, 3170 cannot_modify, 3175 in_use, 3176 locked, 3200 stale_edit_sequence, 3210 invalid_value, 3220 not_authorized, 3231 request_not_processed, 3250 feature_not_enabled, 3260 insufficient_permission, 3261 personal_data_access_denied, 3262 payroll_subscription_required, 3263 read_only_access, 3264 merchant_services_subscription_required

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "edit_sequence": "<edit_sequence>",
      "list_id": "<list_id>"
    },
    "name": "update_price_level"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNoName is the case-insensitive short name of a list object (without ancestors). It must be unique within its hierarchy scope.
list_idYesQuickBooks' ID for the record. Used over `full_name` when both are sent.
is_activeNoIf `is_active` is true, this object is currently enabled for use by QuickBooks. The default value is true.
request_idNoYour own label for the request, sent to QuickBooks as its qbXML `requestID` and echoed in the raw answer (`response_xml`); optional, since the answer's webhook already carries the request's `id`.
currency_refNoA currency record defines how QuickBooks stores and displays a currency. Built-in currency name/code values are fixed; formatting and active status can vary by settings and workflow. Choose at most one of: `price_level_fixed_percentage`, or the set (`currency_ref`, `price_level_per_item`). Members of a set combine with each other, not with the other choices.
edit_sequenceYes`edit_sequence` is a server-generated revision token. It changes each time the object is updated. To modify an existing object, you must send the current `edit_sequence`.
include_qbxmlNoAlso return the qbXML this compiles to, for debugging. Not part of the v2 request.
include_ret_elementNo
price_level_per_itemNoChoose at most one of: `price_level_fixed_percentage`, or the set (`currency_ref`, `price_level_per_item`). Members of a set combine with each other, not with the other choices.
price_level_fixed_percentageNoWhen you create a price level, you must specify whether it is a fixed percentage or a per item price level. Once you create the price level, you can’t change this. Choose at most one of: `price_level_fixed_percentage`, or the set (`currency_ref`, `price_level_per_item`). Members of a set combine with each other, not with the other choices.

Output Schema

NameRequiredDescriptionDefault
urlYesReplace {connection_id} with the customer's connection.
bodyYesThe JSON body: the arguments you passed.
qbxmlNoThe qbXML it compiles to. Only with include_qbxml.
methodYes
headersYesSend with the request. Resent unchanged when no 201 came back, it answers with the request already queued.
webhookYesJSON Schema of the payload POSTed to webhook_url once QuickBooks answers, with this operation's response_json (data shape and status codes).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

B3/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description states the tool 'Modifies a price level', while the annotations declare readOnlyHint=true, destructiveHint=false and idempotentHint=true — a direct conflict about whether this call mutates QuickBooks state. The error enumeration (cannot_modify, locked, stale_edit_sequence, 3263 read_only_access) reinforces the mutation framing rather than resolving it, leaving the agent unable to tell whether the call writes or merely compiles a request.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and the key `currency_ref` restriction are front-loaded, and the return-value sentence clearly explains that the tool emits a v2 request plus a webhook payload description. The 20-entry error-code enumeration is bulky relative to its value but is at least confined to a single trailing sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter nested-schema update with an output schema present, the description covers the per-item constraint, the qbXML wrapper acceptance, the request/webhook return shape, and the error surface. The one thing an agent most needs — confirmation of whether the call actually mutates records given readOnlyHint=true — is exactly what it fails to resolve.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 90%, so the baseline is 3, but the description adds a genuine cross-field constraint not present in the schema: `currency_ref` is only valid with 'per item' price levels. It also notes the `price_level_mod` qbXML wrapper is accepted, which affects how the payload may be built.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ('Modifies a price level'), which cleanly separates it from create_price_level and find_price_levels in the sibling list. It does not explicitly name or contrast those siblings, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this versus create_price_level or find_price_levels, nor any stated preconditions such as needing a current edit_sequence before updating. The only conditional guidance is the inlined constraint that `currency_ref` applies only to 'per item' price levels, which is parameter-level rather than tool-selection guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources