Skip to main content
Glama

QuBe Sync: QuickBooks Desktop API for developers

Create credit card credit

create_credit_card_credit
Read-onlyIdempotent

If a QuickBooks user returns merchandise and receives credit, the credit is entered in QuickBooks and assigned to the appropriate expense account. Typically, the assigned expense account reflects the same account, customer, and class that were assigned when the merchandise was first purchased. (The original purchase would be described by a CreditCardCharge message.)

The credit_card_credit_add 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, 3120 object_not_found, 3140 invalid_reference, 3150 missing_element, 3175 in_use, 3176 locked, 3180 cannot_save, 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, 3270 missing_posting_account

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": {
      "account_ref": "<account_ref>"
    },
    "name": "create_credit_card_credit"
  }
}

Input Schema

NameRequiredDescriptionDefault
memoNoAdditional information.
txn_dateNoThe date of the transaction. In some cases, if you leave `txn_date` out of an -Add message, QuickBooks will prefill `txn_date` with the date of the last-saved transaction of the same type.
def_macroNo`def_macro` lets you assign a reusable name to a returned `txn_id` or `txn_line_id` so later requests can reference it with `useMacro`. This feature requires SDK 2.0+.
ref_numberNo`ref_number` is a user-managed transaction reference (for example, a check number). It can be edited and is not guaranteed to be globally unique.
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`.
account_refYes`account_ref` points to an account in the company file. If both `full_name` and `list_id` are provided, `full_name` is ignored.
exchange_rateNo`exchange_rate` is the rate from this currency to the company’s home currency at AsOfDate. You can supply a rate when adding transactions, but QuickBooks does not provide rates through the SDK.
external_guidNoAllows for the attachment of a user defined GUID value.
include_qbxmlNoAlso return the qbXML this compiles to, for debugging. Not part of the v2 request.
item_line_addNoAn ItemLine is used to track any portion of a transaction that represents the purchase of an “item.” `item_line_add` and `item_group_line_add` combine: any number of each. QuickBooks receives them in that order: every `item_line_add`, then every `item_group_line_add`.
is_tax_includedNoFor future use with international versions of QuickBooks.
expense_line_addNo
payee_entity_refNo`payee_entity_ref` identifies the payee (customer, vendor, employee, or Other Name). If both `full_name` and `list_id` are provided, `full_name` is ignored.
sales_tax_code_refNo`sales_tax_code_ref` points to the sales-tax code used for an item or customer context. QuickBooks includes default TAX and NON codes, and a code can be deleted only when nothing references it.
include_ret_elementNo
item_group_line_addNoRefers to items that are grouped together in QuickBooks for fast entry. `item_line_add` and `item_group_line_add` combine: any number of each. QuickBooks receives them in that order: every `item_line_add`, then every `item_group_line_add`.

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

C2.9/5.0
Behavior3/5

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

The description adds real value beyond the annotations by disclosing that the call returns a v2 request plus a webhook payload (response_json shape and status codes) rather than the created entity, and it enumerates 20+ error codes with names. That return-path detail is the single most useful behavioral statement here. However, it does not state what happens to defaulted fields (e.g. txn_date prefilling is only in the schema), whether the expensed account must match the original charge, or what permissions are required beyond the error code list, and the readOnlyHint=true annotation against a 'create' tool is left unexplained.

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

Conciseness3/5

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

The first paragraph is accounting background that partially earns its place by explaining the default expense-account behavior, but it leads with context instead of the action. The error-code dump is long yet scannable and front-loads the status codes with their names. Nothing is padded, but the most decision-relevant sentence, that this returns a request rather than a saved record, is buried in the middle.

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?

With an output schema, rich annotations, and 88% schema coverage, the definition covers the remaining gaps: return mechanics via webhook response_json, the include_qbxml debug escape hatch, and the full error taxonomy. Given 16 parameters and deep nesting, it is defensible that line-item semantics live in the schema. The missing piece is alternative-tool routing and an explanation of why a create operation carries readOnlyHint=true.

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

Parameters3/5

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

Schema description coverage is 88%, so the schema itself carries nearly all parameter meaning, making 3 the baseline. The description contributes only the note that the qbXML `credit_card_credit_add` wrapper is accepted and the domain rule that the expense account typically mirrors the original purchase. It says nothing about the sole required field account_ref or about how item_line_add and expense_line_add are meant to be combined.

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

Purpose3/5

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

The description opens with accounting narrative about what a credit card credit means in QuickBooks rather than stating plainly 'creates a CreditCardCredit object.' It does eventually clarify the operational shape ('Returns the v2 request to send, and the webhook payload'), which tells an agent the tool compiles a request rather than returning a saved record. It never distinguishes this from close siblings such as create_credit_card_charge, create_ar_refund_credit_card, or create_credit_memo, all of which are plausible picks for a refund scenario.

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?

No guidance on when to choose this over create_ar_refund_credit_card, create_vendor_credit, or create_credit_memo, which are exactly the ambiguous alternatives an agent would weigh for a merchandise return. There are no prerequisites or exclusions either, only the implicit hint that the original purchase would be a CreditCardCharge. The error list indicates failure modes but not when to invoke the tool.

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