> ## Documentation Index > Fetch the complete documentation index at: https://docs.qubesync.com/llms.txt > Use this file to discover all available pages before exploring further. # Update credit memo > qbXML: `CreditMemoModRq`, from qbXML 3.0. The `credit_memo_mod` wrapper from qbXML is also accepted. Some fields in a CreditMemoMod request can’t be cleared. If any of the following fields is included in a credit-memo modify request, it must contain a value: - `customer_ref` - `ar_account_ref` - `template_ref` - `txn_date` - `is_pending` - `due_date` - `ship_date` - `item_sales_tax_ref` - `is_to_be_printed` Within `credit_memo_line_mod` or `credit_memo_line_group_mod`: - `item_ref` - Quantity - Rate - Amount - `sales_tax_code_ref` - `override_item_account_ref` (For more details about what it means for a field to be clearable or not clearable, see [Modify, delete, and void requests and responses](https://developer.intuit.com/app/developer/qbdesktop/docs/develop/exploring-the-quickbooks-desktop-sdk).) Intuit's reference: [CreditMemoMod](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/creditmemomod). ## OpenAPI ````yaml /api-reference/v2/openapi.json put /connections/{connection_id}/credit-memos openapi: 3.1.0 info: contact: email: support@qubesync.com description: > A single generic operation surface for every curated qbXML request QuBe Sync supports, driven directly off the qbXML schema -- see the [MCP server](/mcp-server) to explore available operations interactively. **Every endpoint queues a request and returns it immediately (`201`, a `QueuedRequest`).** QuickBooks Desktop is reached through the customer's Web Connector, which polls QuBe Sync, so the answer arrives seconds to minutes later. **Pass a `webhook_url` with every request**: when QuickBooks has answered, QuBe Sync POSTs the same document to it -- `state` set, `response_json` filled in -- signed with `X-QUBE-Signature` (see the Webhooks guide). `response_json` is the `{status, data}` envelope documented on each operation: `status: "success"` with `data` derived from the qbXML `*Ret` (and `warning`, QuickBooks' code and message, when it carried the request out but warned about it), or `status: "error"` with QuickBooks' own status code and message -- a QuickBooks business error is a *successful* HTTP round trip. `links.self` returns the request on demand (for a dashboard, a retry, a script); it is not the integration path. Send an `Idempotency-Key` header with each request so a call whose answer you never got can be sent again without queueing it twice. Authentication is HTTP Basic with your app's API key as the username and a blank password. Connections themselves (creating one, onboarding, its QWC file and password) are the `/connections` endpoints; every QuickBooks operation is scoped to one of them. title: QuBe Sync API (v2) version: 2.0.0 servers: - description: v2 API url: https://qubesync.com/api/v2 - description: Local development server url: https://dev.qubesync.com/api/v2 security: - apiKey: [] tags: - description: >- Creating and managing the connection (a customer's QuickBooks company file) that every request below is queued against. See the Onboarding guide. name: Connections - description: >- Queueing qbXML you wrote yourself, listing the requests queued on a connection, and discarding one the app no longer wants. A `webhook_url` on each request is the integration path (see the Webhooks guide): the listing is for a dashboard, a script, or catching up after downtime. name: Queued Requests - description: >- Finding the record in a customer's company file that a name means, even written differently: ranked matches from QuBe Sync's index of the file's names, on realtime and simulated connections. See the Matching guide. name: Matching - description: >- Endpoints for publishing workflow definitions, starting runs, and answering a run that is waiting on a decision from your app. A workflow is one JSON statechart document; see the schema at /api/v2/workflows/schema.json. name: Workflows - name: Account Tax Line Infos - name: Accounts - name: Aging Reports - name: Alerts - name: Ar Refund Credit Cards - name: Bar Codes - name: Bill Payment Checks - name: Bill Payment Credit Cards - name: Bill To Pays - name: Billing Rates - name: Bills - name: Budget Summary Reports - name: Build Assemblies - name: Charges - name: Checks - name: Classes - name: Cleared Statuses - name: Companies - name: Company Activities - name: Credit Card Charges - name: Credit Card Credits - name: Credit Memos - name: Currencies - name: Custom Detail Reports - name: Custom Summary Reports - name: Customer Msgs - name: Customer Types - name: Customers - name: Data Event Recovery Infos - name: Data Ext Defs - name: Data Exts - name: Date Driven Terms - name: Deposits - name: Employee Defaults - name: Employees - name: Entities - name: Estimates - name: Form1099 Category Account Mappings - name: General Detail Reports - name: General Summary Reports - name: Hosts - name: Inventory Adjustments - name: Inventory Sites - name: Invoices - name: Item Assemblies Can Builds - name: Item Discounts - name: Item Fixed Assets - name: Item Groups - name: Item Inventories - name: Item Inventory Assemblies - name: Item Non Inventories - name: Item Other Charges - name: Item Payments - name: Item Receipts - name: Item Sales Tax Groups - name: Item Sales Taxes - name: Item Services - name: Item Sites - name: Item Subtotals - name: Items - name: Job Reports - name: Job Types - name: Journal Entries - name: Leads - name: List Deleteds - name: List Displays - name: List Merge - name: Lists - name: Other Names - name: Paychecks - name: Payment Methods - name: Payments - name: Payroll Detail Reports - name: Payroll Item Additions - name: Payroll Item Company Contributions - name: Payroll Item Deductions - name: Payroll Item Direct Deposits - name: Payroll Item Non Wages - name: Payroll Item Taxes - name: Payroll Item Wages - name: Payroll Item Workers Compensations - name: Payroll Items - name: Payroll Last Periods - name: Payroll Liability Adjustments - name: Payroll Liability Checks - name: Payroll Prior Payments - name: Payroll Summary Reports - name: Payroll Year To Date Adjustments - name: Preferences - name: Price Levels - name: Purchase Orders - name: Qb Command Exec - name: Receive Payment To Deposits - name: Receive Payments - name: Sales Orders - name: Sales Receipts - name: Sales Reps - name: Sales Tax Codes - name: Sales Tax Payables - name: Sales Tax Payment Checks - name: Sales Tax Return Lines - name: Sales Tax Returns - name: Ship Methods - name: Special Accounts - name: Special Items - name: Standard Terms - name: Templates - name: Terms - name: Time Reports - name: Time Trackings - name: To Dos - name: Transactions - name: Transfer Inventories - name: Transfers - name: Txn Deleteds - name: Txn Displays - name: Txn Void - name: Txns - name: Unit Of Measure Sets - name: Vehicle Mileages - name: Vehicles - name: Vendor Credits - name: Vendor Types - name: Vendors - name: Workers Comp Codes paths: /connections/{connection_id}/credit-memos: put: tags: - Credit Memos summary: Update credit memo description: >- qbXML: `CreditMemoModRq`, from qbXML 3.0. The `credit_memo_mod` wrapper from qbXML is also accepted. Some fields in a CreditMemoMod request can’t be cleared. If any of the following fields is included in a credit-memo modify request, it must contain a value: - `customer_ref` - `ar_account_ref` - `template_ref` - `txn_date` - `is_pending` - `due_date` - `ship_date` - `item_sales_tax_ref` - `is_to_be_printed` Within `credit_memo_line_mod` or `credit_memo_line_group_mod`: - `item_ref` - Quantity - Rate - Amount - `sales_tax_code_ref` - `override_item_account_ref` (For more details about what it means for a field to be clearable or not clearable, see [Modify, delete, and void requests and responses](https://developer.intuit.com/app/developer/qbdesktop/docs/develop/exploring-the-quickbooks-desktop-sdk).) Intuit's reference: [CreditMemoMod](https://developer.intuit.com/app/developer/qbdesktop/docs/api-reference/qbdesktop/creditmemomod). operationId: updateCreditMemo parameters: - description: >- The connection (a customer's QuickBooks company file) this request is queued for. in: path name: connection_id required: true schema: format: uuid type: string - description: >- Where QuBe Sync POSTs the answered request (this same document with `response_json` filled in), signed with `X-QUBE-Signature`. Send one with every request: it is how answers are delivered. Optional only so a script can queue and look up `links.self` by hand. It must be an absolute http or https URL. It may not contain a username or password, and in production it may not point at localhost or a private, loopback or link-local address. A `qube listen` URL must be one of this app's. in: query name: webhook_url required: false schema: format: uri maxLength: 2048 type: string - $ref: '#/components/parameters/IdempotencyKey' requestBody: content: application/json: example: bill_address: addr1: 123 Main St city: Springfield postal_code: '62701' state: IL customer_ref: full_name: Acme Corp edit_sequence: '1700000000' memo: Monthly service ref_number: '1001' txn_date: '2026-01-15' txn_id: 1A2B-1700000000 schema: properties: ar_account_ref: description: >- `ar_account_ref` points to an Accounts Receivable account. If both `full_name` and `list_id` are provided, `full_name` is ignored. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object bill_address: description: >- This aggregate supports at most five address lines. You can provide a structured address (Addr1-Addr3 plus City/State/`postal_code`/etc.) or use block mode (Addr1-Addr5 only). Do not mix block mode with other address fields. In block mode, each Addr line prints as its own line and is returned in `ship_address_block` or `bill_address_block`. properties: addr1: description: The first line of an address. type: string addr2: description: >- The second line of an address (if a second line is needed). type: string addr3: description: >- The third line of an address (if a third line is needed). type: string addr4: description: >- The fourth line of an address (if a fourth line is needed). type: string addr5: description: >- The fifth line of an address (if a fifth line is needed). type: string city: description: The city name in an address. type: string country: description: >- The country name in an address, or, in returned Host information (HostRet or HostInfo), the country for which this edition of QuickBooks was designed. (Possible values are US, CA, UK, and AU.) type: string note: description: >- In a `bill_address` or `ship_address` aggregate, the Note field value is written at the bottom of the address in the form in which it appears, such as the invoice form. type: string postal_code: description: The postal code in an address. type: string state: description: The state name in an address. type: string type: object class_ref: description: >- Use classes to categorize transactions (for example, by department, location, or work type). Class tracking is off by default in QuickBooks. A `class_ref` points to one class; if both `full_name` and `list_id` are provided, `full_name` is ignored. In InvoiceAdd, a header-level `class_ref` is applied to line items unless you override or clear it on individual lines. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object credit_memo_line_group_mod: description: >- Represents a previously defined group of lines in the credit memo. Compare with CreditMemoLine, which represents just one line in the credit memo. `credit_memo_line_mod` and `credit_memo_line_group_mod` combine: any number of each. QuickBooks receives them in that order: every `credit_memo_line_mod`, then every `credit_memo_line_group_mod`. items: properties: credit_memo_line_mod: description: >- Represents one line in the credit memo. Compare with CreditMemoGroupLine, which represents a previously defined group of lines in the credit memo. items: not: anyOf: - required: - rate - rate_percent - required: - rate - price_level_ref - required: - rate_percent - price_level_ref - required: - serial_number - lot_number properties: amount: description: A monetary amount. type: number class_ref: description: >- Use classes to categorize transactions (for example, by department, location, or work type). Class tracking is off by default in QuickBooks. A `class_ref` points to one class; if both `full_name` and `list_id` are provided, `full_name` is ignored. In InvoiceAdd, a header-level `class_ref` is applied to line items unless you override or clear it on individual lines. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object desc: description: A descriptive text field. type: string inventory_site_location_ref: description: Location within the Inventory Site. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object inventory_site_ref: description: Site where inventory is located. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object item_ref: description: >- `item_ref` may accept all item types or a restricted subset, depending on the request. Examples: PurchaseOrder and Bill do not allow discount or sales-tax items; VehicleMileageAdd requires a service or other-charge item; BillingRateAdd requires a service item. If both `full_name` and `list_id` are provided, `full_name` is ignored. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object lot_number: description: >- The lot number of the asset. Choose at most one of: `serial_number`, or `lot_number`. type: string other1: description: >- Other, Other1, and Other2 are built-in transaction custom fields. Other is transaction-level; Other1 and Other2 are line-level. These fields are always available through the SDK and do not require DataExtDef setup. Template labels in the UI can be renamed, but SDK names remain fixed as Other, Other1, and Other2. type: string other2: description: >- Other, Other1, and Other2 are built-in transaction custom fields. Other is transaction-level; Other1 and Other2 are line-level. These fields are always available through the SDK and do not require DataExtDef setup. Template labels in the UI can be renamed, but SDK names remain fixed as Other, Other1, and Other2. type: string override_item_account_ref: description: >- Refers to a QuickBooks account. If an `override_item_account_ref` aggregate includes both `full_name` and `list_id`, `full_name` will be ignored. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object override_uom_set_ref: description: >- When you modify a transaction line to change the unit of measure used in that line, you use this aggregate to specify the UOM set within which you are choosing an available unit of measure. The “override” here refers to the unit within the set, not the UOM Set itself, which you can’t change or override–the UOM set that can be set or changed only in the item itself via an Item Mod request. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object price_level_ref: description: >- Price levels let you apply custom pricing rules for selected customers. Once assigned, QuickBooks uses those prices automatically on supported sales forms unless explicitly overridden. Choose at most one of: `rate`, or `rate_percent`, or `price_level_ref`. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object quantity: description: >- On transaction lines, QuickBooks can derive one value from the other two among Quantity, Rate, and Amount. If you supply Quantity and Amount, QuickBooks calculates Rate. If you supply Quantity and Rate, QuickBooks calculates Amount. type: number rate: description: >- If you specify both Rate and Amount in a request, the Rate you provide will be ignored, and you will receive a warning. If you specify both Quantity and Amount in an Add request, QuickBooks will use them to calculate Rate. (Rate, Amount, and Quantity can’t be cleared.) Choose at most one of: `rate`, or `rate_percent`, or `price_level_ref`. type: number rate_percent: description: >- Indicates the price of something as a percent. Choose at most one of: `rate`, or `rate_percent`, or `price_level_ref`. type: number sales_tax_code_ref: description: >- `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. If sales tax is disabled, QuickBooks assigns the default non-taxable code. If both `full_name` and `list_id` are provided in `sales_tax_code_ref`, `full_name` is ignored. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object serial_number: description: >- The serial number of the asset. Choose at most one of: `serial_number`, or `lot_number`. type: string service_date: description: >- Indicates the date on which the QuickBooks user performs the service for the customer. format: date type: string tax_amount: type: number txn_line_id: description: >- Identification number of the transaction line. (`txn_line_id` is supported as of v2.0 of the SDK. With qbXML v1.0 and v1.1, `txn_line_id` is always returned as zero.) If you need to add a new transaction line in a transaction Mod request, you can do so by setting the `txn_line_id` to -1. type: string unit_of_measure: description: >- In a transaction line item, the name of the unit of measure selected from within the item’s available units. If the company file is enabled only for single unit of measure per item, this must be the base unit! type: string required: - txn_line_id type: object type: array item_group_ref: description: >- ItemGroup objects represent items that are grouped together for fast entry, and an `item_group_ref` aggregate refers to one of these item groups. In a request, if an `item_group_ref` aggregate includes both `full_name` and `list_id`, `full_name` will be ignored. You can use an ItemGroupQuery request to get information about all the item groups that are set up in the QuickBooks file. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object override_uom_set_ref: description: >- When you modify a transaction line to change the unit of measure used in that line, you use this aggregate to specify the UOM set within which you are choosing an available unit of measure. The “override” here refers to the unit within the set, not the UOM Set itself, which you can’t change or override–the UOM set that can be set or changed only in the item itself via an Item Mod request. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object quantity: description: >- On transaction lines, QuickBooks can derive one value from the other two among Quantity, Rate, and Amount. If you supply Quantity and Amount, QuickBooks calculates Rate. If you supply Quantity and Rate, QuickBooks calculates Amount. type: number txn_line_id: description: >- Identification number of the transaction line. (`txn_line_id` is supported as of v2.0 of the SDK. With qbXML v1.0 and v1.1, `txn_line_id` is always returned as zero.) If you need to add a new transaction line in a transaction Mod request, you can do so by setting the `txn_line_id` to -1. type: string unit_of_measure: description: >- In a transaction line item, the name of the unit of measure selected from within the item’s available units. If the company file is enabled only for single unit of measure per item, this must be the base unit! type: string required: - txn_line_id type: object type: array credit_memo_line_mod: description: >- Represents one line in the credit memo. Compare with CreditMemoGroupLine, which represents a previously defined group of lines in the credit memo. `credit_memo_line_mod` and `credit_memo_line_group_mod` combine: any number of each. QuickBooks receives them in that order: every `credit_memo_line_mod`, then every `credit_memo_line_group_mod`. items: not: anyOf: - required: - rate - rate_percent - required: - rate - price_level_ref - required: - rate_percent - price_level_ref - required: - serial_number - lot_number properties: amount: description: A monetary amount. type: number class_ref: description: >- Use classes to categorize transactions (for example, by department, location, or work type). Class tracking is off by default in QuickBooks. A `class_ref` points to one class; if both `full_name` and `list_id` are provided, `full_name` is ignored. In InvoiceAdd, a header-level `class_ref` is applied to line items unless you override or clear it on individual lines. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object desc: description: A descriptive text field. type: string inventory_site_location_ref: description: Location within the Inventory Site. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object inventory_site_ref: description: Site where inventory is located. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object item_ref: description: >- `item_ref` may accept all item types or a restricted subset, depending on the request. Examples: PurchaseOrder and Bill do not allow discount or sales-tax items; VehicleMileageAdd requires a service or other-charge item; BillingRateAdd requires a service item. If both `full_name` and `list_id` are provided, `full_name` is ignored. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object lot_number: description: >- The lot number of the asset. Choose at most one of: `serial_number`, or `lot_number`. type: string other1: description: >- Other, Other1, and Other2 are built-in transaction custom fields. Other is transaction-level; Other1 and Other2 are line-level. These fields are always available through the SDK and do not require DataExtDef setup. Template labels in the UI can be renamed, but SDK names remain fixed as Other, Other1, and Other2. type: string other2: description: >- Other, Other1, and Other2 are built-in transaction custom fields. Other is transaction-level; Other1 and Other2 are line-level. These fields are always available through the SDK and do not require DataExtDef setup. Template labels in the UI can be renamed, but SDK names remain fixed as Other, Other1, and Other2. type: string override_item_account_ref: description: >- Refers to a QuickBooks account. If an `override_item_account_ref` aggregate includes both `full_name` and `list_id`, `full_name` will be ignored. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object override_uom_set_ref: description: >- When you modify a transaction line to change the unit of measure used in that line, you use this aggregate to specify the UOM set within which you are choosing an available unit of measure. The “override” here refers to the unit within the set, not the UOM Set itself, which you can’t change or override–the UOM set that can be set or changed only in the item itself via an Item Mod request. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object price_level_ref: description: >- Price levels let you apply custom pricing rules for selected customers. Once assigned, QuickBooks uses those prices automatically on supported sales forms unless explicitly overridden. Choose at most one of: `rate`, or `rate_percent`, or `price_level_ref`. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object quantity: description: >- On transaction lines, QuickBooks can derive one value from the other two among Quantity, Rate, and Amount. If you supply Quantity and Amount, QuickBooks calculates Rate. If you supply Quantity and Rate, QuickBooks calculates Amount. type: number rate: description: >- If you specify both Rate and Amount in a request, the Rate you provide will be ignored, and you will receive a warning. If you specify both Quantity and Amount in an Add request, QuickBooks will use them to calculate Rate. (Rate, Amount, and Quantity can’t be cleared.) Choose at most one of: `rate`, or `rate_percent`, or `price_level_ref`. type: number rate_percent: description: >- Indicates the price of something as a percent. Choose at most one of: `rate`, or `rate_percent`, or `price_level_ref`. type: number sales_tax_code_ref: description: >- `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. If sales tax is disabled, QuickBooks assigns the default non-taxable code. If both `full_name` and `list_id` are provided in `sales_tax_code_ref`, `full_name` is ignored. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object serial_number: description: >- The serial number of the asset. Choose at most one of: `serial_number`, or `lot_number`. type: string service_date: description: >- Indicates the date on which the QuickBooks user performs the service for the customer. format: date type: string tax_amount: type: number txn_line_id: description: >- Identification number of the transaction line. (`txn_line_id` is supported as of v2.0 of the SDK. With qbXML v1.0 and v1.1, `txn_line_id` is always returned as zero.) If you need to add a new transaction line in a transaction Mod request, you can do so by setting the `txn_line_id` to -1. type: string unit_of_measure: description: >- In a transaction line item, the name of the unit of measure selected from within the item’s available units. If the company file is enabled only for single unit of measure per item, this must be the base unit! type: string required: - txn_line_id type: object type: array customer_msg_ref: description: >- A standard message such as “Thank you for your business,” or “Please sign and return this estimate to indicate your approval.” A customer message can be included at the bottom of a form. A `customer_msg_ref` aggregate refers to one of the messages on the CustomerMsg list. In a request, if a `customer_msg_ref` aggregate includes both `full_name` and `list_id`, `full_name` will be ignored. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object customer_ref: description: >- `customer_ref` identifies a customer or customer job. If both `full_name` and `list_id` are provided, `full_name` is ignored. In SalesReceipt and ReceivePayment, it identifies who receives credit. In TimeTracking, it identifies who the time can be billed to and is required in TimeTrackingAdd when IsBillable is true. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object customer_sales_tax_code_ref: description: >- Refers to the sales-tax code for sales related to this customer. (That is, it refers to a member of the SalesTaxCode list.) The sales-tax code indicates whether an item is taxable or non-taxable, and why. In a request, if a `customer_sales_tax_code_ref` aggregate includes both `full_name` and `list_id`, `full_name` will be ignored. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object due_date: description: The date on which payment is due. format: date type: string edit_sequence: description: >- `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`. If your value is stale, the update is rejected to prevent overwriting newer changes. type: string exchange_rate: description: >- `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. If your home currency is USD and internet access is available, rates can be downloaded in the QuickBooks UI via Lists > Currency > Activities > Download Latest Exchange Rates. type: number fob: description: >- QuickBooks uses the term FOB, “freight on board,” to indicate the place from which the product is shipped. The FOB has no accounting implications. type: string include_ret_element: items: enum: - ARAccountRef - BillAddress - BillAddressBlock - ClassRef - CreditMemoLineGroupRet - CreditMemoLineRet - CreditRemaining - CreditRemainingInHomeCurrency - CurrencyRef - CustomerMsgRef - CustomerRef - CustomerSalesTaxCodeRef - DataExtRet - DiscountLineRet - DueDate - EditSequence - ExchangeRate - ExternalGUID - FOB - IsPending - IsTaxIncluded - IsToBeEmailed - IsToBePrinted - ItemSalesTaxRef - LinkedTxn - ListID - Memo - Other - OwnerID - PONumber - RefNumber - SalesRepRef - SalesTaxLineRet - SalesTaxPercentage - SalesTaxTotal - ShipAddress - ShipAddressBlock - ShipDate - ShipMethodRef - ShippingLineRet - Subtotal - TemplateRef - TermsRef - TimeCreated - TimeModified - TotalAmount - TxnDate - TxnID - TxnNumber type: string type: array is_pending: description: >- If `is_pending` is set to true, the credit memo hasn’t been completed. Within QuickBooks, you can change the `is_pending` status for a credit memo by choosing “Mark Credit Memo As Pending” or “Mark Credit Memo As Final” from the Edit menu. type: boolean is_tax_included: description: For future use with international versions of QuickBooks. type: boolean is_to_be_emailed: description: >- When enabled, QuickBooks validates the customer email at runtime before sending. If no valid email is available, the request fails. type: boolean is_to_be_printed: description: >- If `is_to_be_printed` is true, QuickBooks queues the form for later printing. It does not print immediately; printing is still a user action in QuickBooks. type: boolean item_sales_tax_ref: description: >- An ItemSalesTax entry represents one tax rate paid to one tax agency. Use it when a transaction needs a single tax calculation. For multi-rate scenarios, use a sales-tax group instead. If both `full_name` and `list_id` are provided for `item_sales_tax_ref`, `list_id` is used. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object memo: description: >- The memo doesn’t print on the credit memo, but does appear in the account register and the customer register. type: string other: description: >- Other, Other1, and Other2 are built-in transaction custom fields. Other is transaction-level; Other1 and Other2 are line-level. These fields are always available through the SDK and do not require DataExtDef setup. Template labels in the UI can be renamed, but SDK names remain fixed as Other, Other1, and Other2. type: string po_number: description: Purchase order number. type: string ref_number: description: >- `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. Some transaction types auto-populate `ref_number` when omitted, based on QuickBooks preferences and numbering state. type: string request_id: description: >- Your 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`. type: string sales_rep_ref: description: >- A sales representative must be on the Employee, Vendor, or Other Names list within QuickBooks. Sales representative’s names and initials appear on the Rep drop-down list on QuickBooks sales forms. A `sales_rep_ref` refers to a person on the SalesRep list. In a request, if a `sales_rep_ref` aggregate includes both `full_name` and `list_id`, `full_name` will be ignored. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object ship_address: description: >- This aggregate supports at most five address lines. You can provide a structured address (Addr1-Addr3 plus City/State/`postal_code`/etc.) or use block mode (Addr1-Addr5 only). Do not mix block mode with other address fields. In block mode, each Addr line prints as its own line and is returned in `ship_address_block` or `bill_address_block`. properties: addr1: description: The first line of an address. type: string addr2: description: >- The second line of an address (if a second line is needed). type: string addr3: description: >- The third line of an address (if a third line is needed). type: string addr4: description: >- The fourth line of an address (if a fourth line is needed). type: string addr5: description: >- The fifth line of an address (if a fifth line is needed). type: string city: description: The city name in an address. type: string country: description: >- The country name in an address, or, in returned Host information (HostRet or HostInfo), the country for which this edition of QuickBooks was designed. (Possible values are US, CA, UK, and AU.) type: string note: description: >- In a `bill_address` or `ship_address` aggregate, the Note field value is written at the bottom of the address in the form in which it appears, such as the invoice form. type: string postal_code: description: The postal code in an address. type: string state: description: The state name in an address. type: string type: object ship_date: description: The date when the product was, or will be, shipped. format: date type: string ship_method_ref: description: >- A shipping method, for example, standard mail or overnight delivery. A `ship_method_ref` aggregate refers to an item on the ShipMethod list. In a request, if a `ship_method_ref` aggregate includes both `full_name` and `list_id`, `full_name` will be ignored. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object template_ref: description: >- QuickBooks templates specify how to print certain transactions. A template query returns the names of all templates that have been defined in QuickBooks. A `template_ref` element refers to one of these templates. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object terms_ref: description: >- Refers to the payment terms associated with this entity. (This will be an item on the DateDrivenTerms or StandardTerms list.) If a `terms_ref` aggregate includes both `full_name` and `list_id`, `full_name` will be ignored. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object txn_date: description: >- The 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. format: date type: string txn_id: description: >- `txn_id` is the unique QuickBooks identifier for a transaction. Use it to reference that transaction in later requests. `txn_id` values are transaction-specific and should not be reused across unrelated transaction types. type: string required: - edit_sequence - txn_id type: object required: true responses: '201': content: application/json: schema: properties: data: allOf: - $ref: '#/components/schemas/QueuedRequest' - properties: response_json: anyOf: - $ref: >- #/components/schemas/updateCreditMemo_response_json - type: 'null' description: '`null` until answered.' type: object required: - data type: object description: >- Queued for the connection's Web Connector. Pass `webhook_url` and QuBe Sync POSTs the answer to it once QuickBooks has answered (see the `answered` callback: its own payload, not this document). `links.self` returns this document on demand, with `response_json` filled in. headers: Idempotent-Replayed: $ref: '#/components/headers/IdempotentReplayed' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/SandboxPaused' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' callbacks: answered: '{$request.query.webhook_url}': post: description: > Verify `X-QUBE-Signature`, answer 2xx within 5 seconds, then branch on `state`: * `response_received` -- QuickBooks accepted it: `response_json` is `status: "success"` with `data`, or, when there is nothing to show, QuickBooks' `message` (a query that matched nothing is a success, not an error). When QuickBooks carried it out but warned about something, `response_json.warning` has its `code` and `message`: `530`, for one, means a field you sent is not supported by the customer's QuickBooks and was not saved. * `error` -- it is over, and QuBe Sync won't try again. With `error.error_type` `quickbooks_business_error`, QuickBooks refused the request: `response_json` is `status: "error"`, and `response_json.error.code` is the status code to branch on. A `3200` (`stale_edit_sequence`: the record changed after you read it) usually comes with the record as it stands in `response_json.error.current`, its current `edit_sequence` included. Compare it with what you read first: when nobody else changed a field your update sets, re-apply your change and send it again with that `edit_sequence`; when someone did, ask your user which value wins rather than overwriting theirs (without `current`, query the record first). Otherwise QuickBooks never answered it: `xml_error` (the request itself was rejected, and will be again as sent), `outcome_unknown` (a write the Web Connector answered with an error in place of QuickBooks' answer: it may have been applied, so look in QuickBooks before sending it again) or `unexpected_error` (the Web Connector's log says more; a query can be sent again). A connection problem never ends here; it is `retryable`, below. * `retryable` -- the Web Connector could not get it into QuickBooks (QuickBooks was not running, the company file was not open or not this connection's, or a window in QuickBooks was in the way), so nothing was applied. QuBe Sync keeps trying on the Web Connector's runs, so don't resend: show the customer `error.user_message` so they can fix it. This webhook comes when the error first appears or changes, not on every try. If you no longer want the request, discard it (`POST /connections/{connection_id}/queued-requests/{id}/discard`). * `timed_out` -- no answer came back: the customer's computer lost its connection, or QuickBooks or the Web Connector was closed, while QuickBooks had the request. QuickBooks may still have applied it, so look before sending it again. `error.error_type` is `timed_out`. * `discarded` -- your app discarded it before the Web Connector picked it up. QuickBooks never got it, so nothing was applied. `error.error_type` is `discarded`, unless it was `retryable` when you discarded it: then `error` is still the connection error that held it up. An iterated query sends one webhook per page, all with the same `id` and each with its own `page_request_id` and `page`; `iteration_state` is `done` on the last page, which can arrive before earlier ones, so the import is complete once every page from 1 to the `done` page's `page` has been handled. Deliveries can arrive out of order and, after a retry, more than once: key on `page_request_id` plus `state`. A `retryable` webhook is not final: the answer that follows carries the same `id` and `page_request_id` with a different `state`, and only a repeat of the same `state` is a duplicate. A body that would be over 1 MB comes without `response_xml`: `response_xml_omitted` is true, and `links.self` is where to GET it; `response_json` is always there. If webhooks stop arriving altogether, the Web Connector on the customer's PC has most likely stopped calling in; requests wait until it does. Intuit's guide to its errors: https://quickbooks.intuit.com/learn-support/en-us/help-article/open-programs/fix-common-web-connector-errors-quickbooks-desktop/L9slolvg0_US_en_US requestBody: content: application/json: schema: description: >- POSTed to `webhook_url` as JSON, signed with `X-QUBE-Signature` (`t=,v1=." with your app's webhook secret>`). properties: app_id: description: Your app's id. format: uuid type: string app_name: type: string error: description: >- Set when `state` is `error`, `retryable`, `timed_out` or `discarded`. `error_type` says where it failed: for a `timed_out` request it is `timed_out`, and for a `discarded` one `discarded`, unless the request was `retryable` when your app discarded it, which keeps the connection error that held it up. `user_message` is safe to show an end user; `error_code` is QuickBooks' own status code for a business error, `hresult` the Web Connector's for a connection/XML error; `debug_message` is for you. properties: debug_message: description: >- Which element of the request the value came from, when known. type: - string - 'null' error_code: description: QuickBooks' statusCode, for a business error. type: - integer - 'null' error_type: description: >- `quickbooks_business_error`: QuickBooks refused the request -- `response_json.error` has its code. `quickbooks_connection_error`: the Web Connector ran on the customer's PC but could not get the request into QuickBooks, so nothing was applied -- QuickBooks was not running, the company file was not open or not the one this connection belongs to, or a window or message box open in QuickBooks was in the way. Only the customer can fix that, and `user_message` tells them how. `xml_error`: QuickBooks could not parse the qbXML; sent again as-is, it fails again. `outcome_unknown`: a write the Web Connector answered with an error in place of QuickBooks' answer, so whether QuickBooks applied it is not known: look in QuickBooks before sending it again. `unexpected_error`: anything else; for a query, which changes nothing, sending it again is safe. `timed_out`: no answer came back -- the customer's computer lost its connection, or QuickBooks or the Web Connector was closed, while QuickBooks had the request. QuickBooks may still have applied it, so look before sending it again. `discarded`: your app discarded it before the Web Connector picked it up, so QuickBooks never got it. `response_too_large`: QuickBooks answered, but with more than QuBe Sync accepts for one answer (4 MB as the Web Connector sends it, about 3 MB of qbXML), so the answer wasn't kept and `response_json` is null. QuickBooks ran the request. Page the query (`iterator` and a smaller `max_returned`), or narrow it when QuickBooks doesn't page it; for a write, look before sending it again. Web Connector problems on the customer's PC (its password, log file, the .QWC file) never reach QuBe Sync as an error: the Web Connector just stops calling in, and requests wait. Intuit's guide for those: https://quickbooks.intuit.com/learn-support/en-us/help-article/open-programs/fix-common-web-connector-errors-quickbooks-desktop/L9slolvg0_US_en_US enum: - xml_error - quickbooks_connection_error - quickbooks_business_error - unexpected_error - response_too_large - outcome_unknown - timed_out - discarded type: string hresult: description: >- The Web Connector's HRESULT (e.g. `0x80040400`), for a connection or XML error. Informational: branch on `error_type`, not on this. type: - string - 'null' message: description: >- The raw message from QuickBooks or the Web Connector; for `timed_out` and `discarded`, which neither sent, QuBe Sync's own. type: string user_message: description: A friendly message for the end user. type: string type: - object - 'null' id: description: >- The request's id, as the 201 returned it. For an iterated query, every page carries the first page's id here. format: uuid type: string iteration_state: description: >- `continue`: more pages will follow, each its own webhook. `done`: this was the last page. `max_sandbox_iterations_reached`: a sandbox app's page limit stopped the iteration. enum: - not_applicable - continue - done - max_sandbox_iterations_reached type: string links: description: Present only with `response_xml_omitted`. properties: self: description: >- This page's request in the API, `response_xml` included. format: uri type: string type: object page: description: The page number, when iterated. type: - integer - 'null' page_request_id: description: >- This page's own id. Equal to `id` except on later pages of an iterated query. format: uuid type: string response_json: $ref: '#/components/schemas/updateCreditMemo_response_json' response_xml: description: >- QuickBooks' raw qbXML answer. `response_json` is the same, summarized. One answer can be at most 4 MB as the Web Connector sends it, about 3 MB of qbXML; QuickBooks' answer over that isn't kept: this is null and `error.error_type` is `response_too_large`. A webhook whose body would be over 1 MB is sent without it: null, with `response_xml_omitted` true; fetch it from `links.self`. type: - string - 'null' response_xml_omitted: description: >- Present, and true, only when `response_xml` was left out to keep the body under 1 MB. `response_json` is still here; GET `links.self` for `response_xml`. type: boolean sandbox: description: Whether the app is a sandbox app. type: boolean state: description: >- `response_received`: QuickBooks accepted it; read `response_json`. `error`: it is over and QuBe Sync won't try again -- see `error`, and `response_json.error` for a QuickBooks business error; with `error_type` `outcome_unknown` a write may still have been applied, so look before sending it again. `retryable`: QuickBooks could not be reached and QuBe Sync keeps trying; show the customer `error.user_message` so they can fix it. `timed_out`: no answer came back -- the customer's computer lost its connection, or QuickBooks or the Web Connector was closed, mid-request. QuickBooks may still have applied it, so look before sending it again. `discarded`: your app discarded it before the Web Connector picked it up, so QuickBooks never got it. Both carry an `error`. enum: - response_received - error - retryable - timed_out - discarded type: string timestamp: description: Unix seconds; the same `t` the signature covers. type: integer required: - app_id - app_name - sandbox - timestamp - id - page_request_id - state - response_json - error type: object required: true responses: 2XX: description: >- Received. Anything else is retried with backoff for about 8 hours. summary: QuickBooks answered (or the request failed) method: post type: path path: '{$request.query.webhook_url}' components: parameters: IdempotencyKey: description: >- Makes a retry safe when you never got the answer to a call: a timeout, a dropped connection, a worker that crashed. Send a new key (a UUID, say) with each request you mean to make once, and the same key when you send that request again. A repeat with the key and the same method, path, query and body answers `201` with what the first call created, as it is now, marked `Idempotent-Replayed: true`, and queues nothing. The same key with a different request is a `422`. A key belongs to your app (sandbox and production apps never share one), lasts as long as what it created, and is 1 to 255 printable ASCII characters. example: 9b2f6c1e-0d4a-4f7e-8a7b-2a1c3d4e5f60 in: header name: Idempotency-Key required: false schema: maxLength: 255 minLength: 1 pattern: ^[\x20-\x7E]+$ type: string schemas: QueuedRequest: properties: error: description: >- Set when `state` is `error`, `retryable`, `timed_out` or `discarded`. `error_type` says where it failed: for a `timed_out` request it is `timed_out`, and for a `discarded` one `discarded`, unless the request was `retryable` when your app discarded it, which keeps the connection error that held it up. `user_message` is safe to show an end user; `error_code` is QuickBooks' own status code for a business error, `hresult` the Web Connector's for a connection/XML error; `debug_message` is for you. properties: debug_message: description: Which element of the request the value came from, when known. type: - string - 'null' error_code: description: QuickBooks' statusCode, for a business error. type: - integer - 'null' error_type: description: >- `quickbooks_business_error`: QuickBooks refused the request -- `response_json.error` has its code. `quickbooks_connection_error`: the Web Connector ran on the customer's PC but could not get the request into QuickBooks, so nothing was applied -- QuickBooks was not running, the company file was not open or not the one this connection belongs to, or a window or message box open in QuickBooks was in the way. Only the customer can fix that, and `user_message` tells them how. `xml_error`: QuickBooks could not parse the qbXML; sent again as-is, it fails again. `outcome_unknown`: a write the Web Connector answered with an error in place of QuickBooks' answer, so whether QuickBooks applied it is not known: look in QuickBooks before sending it again. `unexpected_error`: anything else; for a query, which changes nothing, sending it again is safe. `timed_out`: no answer came back -- the customer's computer lost its connection, or QuickBooks or the Web Connector was closed, while QuickBooks had the request. QuickBooks may still have applied it, so look before sending it again. `discarded`: your app discarded it before the Web Connector picked it up, so QuickBooks never got it. `response_too_large`: QuickBooks answered, but with more than QuBe Sync accepts for one answer (4 MB as the Web Connector sends it, about 3 MB of qbXML), so the answer wasn't kept and `response_json` is null. QuickBooks ran the request. Page the query (`iterator` and a smaller `max_returned`), or narrow it when QuickBooks doesn't page it; for a write, look before sending it again. Web Connector problems on the customer's PC (its password, log file, the .QWC file) never reach QuBe Sync as an error: the Web Connector just stops calling in, and requests wait. Intuit's guide for those: https://quickbooks.intuit.com/learn-support/en-us/help-article/open-programs/fix-common-web-connector-errors-quickbooks-desktop/L9slolvg0_US_en_US enum: - xml_error - quickbooks_connection_error - quickbooks_business_error - unexpected_error - response_too_large - outcome_unknown - timed_out - discarded type: string hresult: description: >- The Web Connector's HRESULT (e.g. `0x80040400`), for a connection or XML error. Informational: branch on `error_type`, not on this. type: - string - 'null' message: description: >- The raw message from QuickBooks or the Web Connector; for `timed_out` and `discarded`, which neither sent, QuBe Sync's own. type: string user_message: description: A friendly message for the end user. type: string type: - object - 'null' id: description: Unique identifier for the queued request format: uuid type: string inserted_at: description: When the request was queued format: date-time type: string iteration_state: description: >- Whether this response is part of an ongoing iteration, and if so, whether more pages remain. Use this (not `state`) to tell whether a multi-page response is complete. enum: - not_applicable - continue - done - max_sandbox_iterations_reached type: string links: properties: connection_ui: format: uri type: string pages: description: >- The pages of a multi-page (iterated) response answered so far, oldest first, a page of them at a time (`page`, `page_size`), each with its own `iteration_state`. Each page is also delivered to `webhook_url` as it is answered. format: uri type: string self: description: >- This request, on demand (a dashboard link, a retry). The answer itself arrives at `webhook_url`. format: uri type: string ui: description: The request in the QuBe Sync dashboard. format: uri type: string required: - self - ui - connection_ui - pages type: object original_request_id: description: >- The id of the first page of this request's iteration. Equal to `id` on the first page itself. format: uuid type: string page: description: The page number, for a multi-page (iterated) response nullable: true type: integer request_types: description: The qbXML request type(s) compiled into this request items: type: string type: array request_xml: description: >- The qbXML sent to QuickBooks: compiled from the operation and its parameters, or as written for `POST /connections/{connection_id}/queued-requests`. A character above ASCII reaches QuickBooks as a character reference (`é`). type: string response_json: description: QuBe Sync's summary of the answer, once the request is completed nullable: true type: object response_xml: description: >- The qbXML response from QuickBooks. One answer can be at most 4 MB as the Web Connector sends it, about 3 MB of qbXML; QuickBooks' answer over that isn't kept: this is null and `error.error_type` is `response_too_large`. nullable: true type: string state: description: >- `waiting`/`retryable`/`ticketed`/`sent` while the Web Connector is on its way; `response_received` once QuickBooks answered successfully (read `response_json.data`, and `response_json.warning` when QuickBooks warned about something it did); `error` when it did not -- the Web Connector could not reach QuickBooks, the qbXML was rejected, or QuickBooks answered with a business error such as 3100 (then `error.error_type` is `quickbooks_business_error` and `response_json` still carries QuickBooks' own `{status: "error", error: {code, type, message}}`); `timed_out` when no answer came back (QuickBooks may still have applied it, so look before sending it again) and `discarded` when your app discarded it before the Web Connector picked it up. Both carry an `error`. enum: - waiting - retryable - ticketed - sent - response_received - error - timed_out - discarded type: string webhook_attempts: items: type: object type: array webhook_error: nullable: true type: string webhook_state: enum: - not_applicable - pending - succeeded - failed type: string webhook_url: format: uri nullable: true type: string required: - id - state - request_xml - links type: object updateCreditMemo_response_json: description: >- QuBe Sync's summary of QuickBooks' answer. Only an `Error` severity from QuickBooks is `status: "error"` (and makes the request's `state` `error`), so a query that matched nothing is still `success`. A `Warn` severity is a `success` with `warning` beside it. oneOf: - properties: data: oneOf: - properties: discount_line_ret: not: anyOf: - required: - amount - rate_percent properties: account_ref: properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object amount: description: |- A monetary amount. Choose at most one of: `amount`, or `rate_percent`. type: number is_taxable: type: boolean rate_percent: description: |- Indicates the price of something as a percent. Choose at most one of: `amount`, or `rate_percent`. type: number type: object ship_address: description: >- This aggregate supports at most five address lines. You can provide a structured address (Addr1-Addr3 plus City/State/`postal_code`/etc.) or use block mode (Addr1-Addr5 only). Do not mix block mode with other address fields. In block mode, each Addr line prints as its own line and is returned in `ship_address_block` or `bill_address_block`. properties: addr1: description: The first line of an address. type: string addr2: description: >- The second line of an address (if a second line is needed). type: string addr3: description: >- The third line of an address (if a third line is needed). type: string addr4: description: >- The fourth line of an address (if a fourth line is needed). type: string addr5: description: >- The fifth line of an address (if a fifth line is needed). type: string city: description: The city name in an address. type: string country: description: >- The country name in an address, or, in returned Host information (HostRet or HostInfo), the country for which this edition of QuickBooks was designed. (Possible values are US, CA, UK, and AU.) type: string note: description: >- In a `bill_address` or `ship_address` aggregate, the Note field value is written at the bottom of the address in the form in which it appears, such as the invoice form. type: string postal_code: description: The postal code in an address. type: string state: description: The state name in an address. type: string type: object fob: description: >- QuickBooks uses the term FOB, “freight on board,” to indicate the place from which the product is shipped. The FOB has no accounting implications. type: string bill_address: description: >- This aggregate supports at most five address lines. You can provide a structured address (Addr1-Addr3 plus City/State/`postal_code`/etc.) or use block mode (Addr1-Addr5 only). Do not mix block mode with other address fields. In block mode, each Addr line prints as its own line and is returned in `ship_address_block` or `bill_address_block`. properties: addr1: description: The first line of an address. type: string addr2: description: >- The second line of an address (if a second line is needed). type: string addr3: description: >- The third line of an address (if a third line is needed). type: string addr4: description: >- The fourth line of an address (if a fourth line is needed). type: string addr5: description: >- The fifth line of an address (if a fifth line is needed). type: string city: description: The city name in an address. type: string country: description: >- The country name in an address, or, in returned Host information (HostRet or HostInfo), the country for which this edition of QuickBooks was designed. (Possible values are US, CA, UK, and AU.) type: string note: description: >- In a `bill_address` or `ship_address` aggregate, the Note field value is written at the bottom of the address in the form in which it appears, such as the invoice form. type: string postal_code: description: The postal code in an address. type: string state: description: The state name in an address. type: string type: object credit_memo_line_group_ret: description: >- Represents a previously defined group of lines in the credit memo. Compare with CreditMemoLine, which represents just one line in the credit memo. `credit_memo_line_ret` and `credit_memo_line_group_ret` combine: any number of each. items: properties: credit_memo_line_ret: description: >- Represents one line in the credit memo. Compare with CreditMemoGroupLine, which represents a previously defined group of lines in the credit memo. items: not: anyOf: - required: - rate - rate_percent - required: - serial_number - lot_number properties: amount: description: A monetary amount. type: number class_ref: description: >- Use classes to categorize transactions (for example, by department, location, or work type). Class tracking is off by default in QuickBooks. A `class_ref` points to one class; if both `full_name` and `list_id` are provided, `full_name` is ignored. In InvoiceAdd, a header-level `class_ref` is applied to line items unless you override or clear it on individual lines. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object credit_card_txn_info: description: >- Contains data from the credit card transaction used in the payment. This data originates from a previous qbmsXML credit card transaction. The data following the element `credit_card_txn_input_info`” data is the data from the original qbmsXML request. The “`credit_card_txn_result_info`” is the data from the original qbmsXML response. properties: credit_card_txn_input_info: description: >- This contains data originally supplied in the QBMS transaction request. This information block shouldn’t be used in CreditMemo requests for QuickBooks 2007 and new versions. Instead, use the ARRefundCreditCard request. properties: commercial_card_code: description: >- This optional field is used only for Visa and Master Card commercial cards. There are three types of these cards: purchase, corporate, and business. Normally, special lower transaction fee rates apply when these cards are used and this field is filled out. If this field is left blank, then the usual (and higher) discount rate applies. type: string credit_card_address: description: >- The address associated with this credit card. type: string credit_card_number: description: >- Credit-card number for this customer or this payment. Beginning with qbXML spec 6.0 and QuickBooks 2007, you must mask the credit card number with lower case “x” and no dashes. For example, xxxxxxxxxxxx1234. type: string credit_card_postal_code: description: >- The postal code associated with the address for this credit card. type: string credit_card_txn_type: description: >- Indicates the QBMS transaction from which the current transaction data originated, for example, Charge, Authorization, Capture, Refund, VoiceAuthorization, or Void. enum: - Authorization - Capture - Charge - Refund - VoiceAuthorization type: string expiration_month: description: The month when the credit card expires. maximum: 12 minimum: 1 type: integer expiration_year: description: The year when the credit card expires. type: integer name_on_card: description: The name on the customer’s credit card. type: string transaction_mode: description: >- Indicates whether this transaction came from a card swipe (tmCardPresent) or not (tmCardNotPresent). enum: - CardNotPresent - CardPresent type: string type: object credit_card_txn_result_info: description: >- This contains data returned in the QBMS transaction response. This information block shouldn’t be used in CreditMemo requests for QuickBooks 2007 and new versions. Instead, use the ARRefundCreditCard request. properties: authorization_code: description: >- The authorization code is returned from the credit card processor to indicate that the charge will be paid by the card issuer. In a voice authorization request (CustomerCreditCardVoiceAuthRq), the authorization code is supplied by the card issuer over the telephone. type: string avs_street: description: >- This field contains the value avssPass if the street address supplied in the transaction request matches the customer’s address on file at the card issuer. It contains the value avssFail if there isn’t a match, or avssNotAvailable if the card issuer doesn’t support AVS. Note: This field was required in qbXML 4.1, but is optional in qbXML 5.0 and later. enum: - Fail - NotAvailable - Pass type: string avs_zip: description: >- This field contains the value avszPass if the customer postal ZIP code supplied in the transaction request matches the customer’s postal code recognized at the card issuer. It contains the value avszFail if there isn’t a match, or avszNotAvailable if the card issuer doesn’t support AVS. Note: This field was required in qbXML 4.1, but is optional in qbXML 5.0 and later. enum: - Fail - NotAvailable - Pass type: string card_security_code_match: description: >- This field contains the value Pass if the card security code supplied in the transaction request matches the card security code recognized for that credit card number at the card issuer. It contains the value Fail if there isn’t a match. enum: - Fail - NotAvailable - Pass type: string client_trans_id: description: >- This value is returned from QBMS transactions for future use by the QuickBooks Reconciliation feature. type: string credit_card_trans_id: description: >- This transaction ID is returned from the credit card processor. You should save this value for any possible QBMS SDK transaction requests that need it, for example, CustomerCreditCardTxnVoidRq, or CustomerCreditCardCaptureRq. type: string merchant_account_number: description: >- This is the QBMS account number of the merchant who is running the transaction using the customer’s credit card. It is returned from the transaction request and should be stored for subsequent transactions, such as using it in the QB SDK SalesReceiptAdd, ReceivePaymentAdd, ARRefundCreditCard requests to save the transaction data in QuickBooks. type: string payment_grouping_code: description: >- Internal code needed for the QuickBooks reconciliation feature, if integrating with QuickBooks. This value is returned in the QBMS response to a QBMS transaction request, and must be subsequently supplied by your application in the QB SDK ReceivePaymentAdd or SalesReceiptAdd request. type: integer payment_status: description: >- Indicates payment processing status as known by QuickBooks/QBMS integration state. `psCompleted` indicates confirmed success; `psUnknown` indicates status could not be definitively confirmed. enum: - Completed - Unknown type: string recon_batch_id: description: >- This value is returned by QBMS from the transaction request, and is used internally by the QuickBooks/QBMS Recon (reconcile) feature. You should save this value without modification and include it in the QB SDK SalesReceiptAdd or ReceivePaymentAdd requests if you want to save the transaction data in QuickBooks. type: string result_code: description: >- This contains the status code returned in the original QBMS transaction response. type: integer result_message: description: >- This contains the status message returned in the original QBMS transaction response. type: string txn_authorization_stamp: description: >- This value is used to support the credit card transaction Reconcile feature within QuickBooks. type: integer txn_authorization_time: description: >- Timestamp indicating the time in which the card processor authorized the transaction. format: date-time type: string type: object type: object data_ext_ret: items: properties: data_ext_name: description: >- The name of the data extension. If this is a custom field, `data_ext_name` will be visible as a label in the QuickBooks user interface. Also because `owner_id` and `data_ext_name` together make the data extension unique, and because custom fields all have the same `owner_id` of zero, the `data_ext_name` must be a unique value among existing custom fields. type: string data_ext_type: description: >- The field’s data type, which corresponds to a qbXML data type. In an IDataExtDefAdd request object, if this is a custom field, `data_ext_type` must be detSTR255TYPE. enum: - AMTTYPE - DATETIMETYPE - INTTYPE - PERCENTTYPE - PRICETYPE - QUANTYPE - STR1024TYPE - STR255TYPE type: string data_ext_value: description: >- The data in this field. The maximum length of `data_ext_value` will depend on the `data_ext_type` of this data extension. For example, if `data_ext_type` is STR255TYPE, the maximum length of `data_ext_value` is 255 characters. If `data_ext_type` is STR1024TYPE, the maximum size of `data_ext_value` is 1KB. type: string owner_id: description: >- `owner_id` identifies who owns the data extension. Use 0 for QuickBooks custom fields that appear in the UI, or use a GUID for private extensions owned by an app. Keep private GUIDs confidential unless you intentionally share extensions across apps. If you do share them, both apps must use the same `owner_id` and `data_ext_name`, because that pair uniquely identifies the extension. type: string type: object type: array desc: description: A descriptive text field. type: string inventory_site_location_ref: description: Location within the Inventory Site. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object inventory_site_ref: description: Site where inventory is located. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object is_taxable: type: boolean item_ref: description: >- `item_ref` may accept all item types or a restricted subset, depending on the request. Examples: PurchaseOrder and Bill do not allow discount or sales-tax items; VehicleMileageAdd requires a service or other-charge item; BillingRateAdd requires a service item. If both `full_name` and `list_id` are provided, `full_name` is ignored. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object lot_number: description: >- The lot number of the asset. Choose at most one of: `serial_number`, or `lot_number`. type: string other1: description: >- Other, Other1, and Other2 are built-in transaction custom fields. Other is transaction-level; Other1 and Other2 are line-level. These fields are always available through the SDK and do not require DataExtDef setup. Template labels in the UI can be renamed, but SDK names remain fixed as Other, Other1, and Other2. type: string other2: description: >- Other, Other1, and Other2 are built-in transaction custom fields. Other is transaction-level; Other1 and Other2 are line-level. These fields are always available through the SDK and do not require DataExtDef setup. Template labels in the UI can be renamed, but SDK names remain fixed as Other, Other1, and Other2. type: string override_uom_set_ref: description: >- When you modify a transaction line to change the unit of measure used in that line, you use this aggregate to specify the UOM set within which you are choosing an available unit of measure. The “override” here refers to the unit within the set, not the UOM Set itself, which you can’t change or override–the UOM set that can be set or changed only in the item itself via an Item Mod request. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object quantity: description: >- On transaction lines, QuickBooks can derive one value from the other two among Quantity, Rate, and Amount. If you supply Quantity and Amount, QuickBooks calculates Rate. If you supply Quantity and Rate, QuickBooks calculates Amount. type: number rate: description: >- If you specify both Rate and Amount in a request, the Rate you provide will be ignored, and you will receive a warning. If you specify both Quantity and Amount in an Add request, QuickBooks will use them to calculate Rate. (Rate, Amount, and Quantity can’t be cleared.) Choose at most one of: `rate`, or `rate_percent`. type: number rate_percent: description: >- Indicates the price of something as a percent. Choose at most one of: `rate`, or `rate_percent`. type: number sales_tax_code_ref: description: >- `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. If sales tax is disabled, QuickBooks assigns the default non-taxable code. If both `full_name` and `list_id` are provided in `sales_tax_code_ref`, `full_name` is ignored. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object serial_number: description: >- The serial number of the asset. Choose at most one of: `serial_number`, or `lot_number`. type: string service_date: description: >- Indicates the date on which the QuickBooks user performs the service for the customer. format: date type: string tax_amount: type: number txn_line_id: description: >- Identification number of the transaction line. (`txn_line_id` is supported as of v2.0 of the SDK. With qbXML v1.0 and v1.1, `txn_line_id` is always returned as zero.) If you need to add a new transaction line in a transaction Mod request, you can do so by setting the `txn_line_id` to -1. type: string unit_of_measure: description: >- In a transaction line item, the name of the unit of measure selected from within the item’s available units. If the company file is enabled only for single unit of measure per item, this must be the base unit! type: string type: object type: array data_ext_ret: items: properties: data_ext_name: description: >- The name of the data extension. If this is a custom field, `data_ext_name` will be visible as a label in the QuickBooks user interface. Also because `owner_id` and `data_ext_name` together make the data extension unique, and because custom fields all have the same `owner_id` of zero, the `data_ext_name` must be a unique value among existing custom fields. type: string data_ext_type: description: >- The field’s data type, which corresponds to a qbXML data type. In an IDataExtDefAdd request object, if this is a custom field, `data_ext_type` must be detSTR255TYPE. enum: - AMTTYPE - DATETIMETYPE - INTTYPE - PERCENTTYPE - PRICETYPE - QUANTYPE - STR1024TYPE - STR255TYPE type: string data_ext_value: description: >- The data in this field. The maximum length of `data_ext_value` will depend on the `data_ext_type` of this data extension. For example, if `data_ext_type` is STR255TYPE, the maximum length of `data_ext_value` is 255 characters. If `data_ext_type` is STR1024TYPE, the maximum size of `data_ext_value` is 1KB. type: string owner_id: description: >- `owner_id` identifies who owns the data extension. Use 0 for QuickBooks custom fields that appear in the UI, or use a GUID for private extensions owned by an app. Keep private GUIDs confidential unless you intentionally share extensions across apps. If you do share them, both apps must use the same `owner_id` and `data_ext_name`, because that pair uniquely identifies the extension. type: string type: object type: array desc: description: A descriptive text field. type: string is_print_items_in_group: description: >- If true, a list of this group’s individual items their amounts will appear on printed forms. type: boolean item_group_ref: description: >- ItemGroup objects represent items that are grouped together for fast entry, and an `item_group_ref` aggregate refers to one of these item groups. In a request, if an `item_group_ref` aggregate includes both `full_name` and `list_id`, `full_name` will be ignored. You can use an ItemGroupQuery request to get information about all the item groups that are set up in the QuickBooks file. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object override_uom_set_ref: description: >- When you modify a transaction line to change the unit of measure used in that line, you use this aggregate to specify the UOM set within which you are choosing an available unit of measure. The “override” here refers to the unit within the set, not the UOM Set itself, which you can’t change or override–the UOM set that can be set or changed only in the item itself via an Item Mod request. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object quantity: description: >- On transaction lines, QuickBooks can derive one value from the other two among Quantity, Rate, and Amount. If you supply Quantity and Amount, QuickBooks calculates Rate. If you supply Quantity and Rate, QuickBooks calculates Amount. type: number service_date: description: >- Indicates the date on which the QuickBooks user performs the service for the customer. format: date type: string total_amount: description: Subtotal plus `sales_tax_total`. type: number txn_line_id: description: >- Identification number of the transaction line. (`txn_line_id` is supported as of v2.0 of the SDK. With qbXML v1.0 and v1.1, `txn_line_id` is always returned as zero.) If you need to add a new transaction line in a transaction Mod request, you can do so by setting the `txn_line_id` to -1. type: string unit_of_measure: description: >- In a transaction line item, the name of the unit of measure selected from within the item’s available units. If the company file is enabled only for single unit of measure per item, this must be the base unit! type: string type: object type: array txn_number: description: An identifying number for this transaction. type: integer sales_tax_percentage: description: The percentage charged for sales tax. type: number other: description: >- Other, Other1, and Other2 are built-in transaction custom fields. Other is transaction-level; Other1 and Other2 are line-level. These fields are always available through the SDK and do not require DataExtDef setup. Template labels in the UI can be renamed, but SDK names remain fixed as Other, Other1, and Other2. type: string ship_address_block: description: >- The address expressed as an address block of Addr1 through Addr5, depending on the number of lines in the original request that created the address. properties: addr1: description: The first line of an address. type: string addr2: description: >- The second line of an address (if a second line is needed). type: string addr3: description: >- The third line of an address (if a third line is needed). type: string addr4: description: >- The fourth line of an address (if a fourth line is needed). type: string addr5: description: >- The fifth line of an address (if a fifth line is needed). type: string type: object time_modified: description: Time the object was last modified. format: date-time type: string is_tax_included: description: >- For future use with international versions of QuickBooks. type: boolean customer_sales_tax_code_ref: description: >- Refers to the sales-tax code for sales related to this customer. (That is, it refers to a member of the SalesTaxCode list.) The sales-tax code indicates whether an item is taxable or non-taxable, and why. In a request, if a `customer_sales_tax_code_ref` aggregate includes both `full_name` and `list_id`, `full_name` will be ignored. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object is_to_be_printed: description: >- If `is_to_be_printed` is true, QuickBooks queues the form for later printing. It does not print immediately; printing is still a user action in QuickBooks. type: boolean is_pending: description: >- If `is_pending` is set to true, the credit memo hasn’t been completed. Within QuickBooks, you can change the `is_pending` status for a credit memo by choosing “Mark Credit Memo As Pending” or “Mark Credit Memo As Final” from the Edit menu. type: boolean ref_number: description: >- `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. Some transaction types auto-populate `ref_number` when omitted, based on QuickBooks preferences and numbering state. type: string linked_txn: items: properties: amount: description: A monetary amount. type: number link_type: description: >- Indicates the nature of the link between the transactions: ltAMTTYPE means the two transactions are linked based on an amount value (for example an invoice linked to a payment). ltQUANTYPE means the two transactions are linked based on a quantity. This affects transactions that are linked to sales orders, estimates and purchase orders. enum: - AMTTYPE - QUANTYPE type: string ref_number: description: >- `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. Some transaction types auto-populate `ref_number` when omitted, based on QuickBooks preferences and numbering state. type: string txn_date: description: >- The 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. format: date type: string txn_id: description: >- `txn_id` is the unique QuickBooks identifier for a transaction. Use it to reference that transaction in later requests. `txn_id` values are transaction-specific and should not be reused across unrelated transaction types. type: string txn_line_detail: items: properties: amount: description: A monetary amount. type: number txn_line_id: description: >- Identification number of the transaction line. (`txn_line_id` is supported as of v2.0 of the SDK. With qbXML v1.0 and v1.1, `txn_line_id` is always returned as zero.) If you need to add a new transaction line in a transaction Mod request, you can do so by setting the `txn_line_id` to -1. type: string type: object type: array txn_type: description: The type of transaction. enum: - ARRefundCreditCard - Bill - BillPaymentCheck - BillPaymentCreditCard - BuildAssembly - Charge - Check - CreditCardCharge - CreditCardCredit - CreditMemo - Deposit - Estimate - InventoryAdjustment - Invoice - ItemReceipt - JournalEntry - LiabilityAdjustment - Paycheck - PayrollLiabilityCheck - PurchaseOrder - ReceivePayment - SalesOrder - SalesReceipt - SalesTaxPaymentCheck - Transfer - VendorCredit - YTDAdjustment type: string type: object type: array txn_id: description: >- `txn_id` is the unique QuickBooks identifier for a transaction. Use it to reference that transaction in later requests. `txn_id` values are transaction-specific and should not be reused across unrelated transaction types. type: string customer_msg_ref: description: >- A standard message such as “Thank you for your business,” or “Please sign and return this estimate to indicate your approval.” A customer message can be included at the bottom of a form. A `customer_msg_ref` aggregate refers to one of the messages on the CustomerMsg list. In a request, if a `customer_msg_ref` aggregate includes both `full_name` and `list_id`, `full_name` will be ignored. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object bill_address_block: description: >- The address expressed as an address block of Addr1 through Addr5, depending on the number of lines in the original request that created the address. properties: addr1: description: The first line of an address. type: string addr2: description: >- The second line of an address (if a second line is needed). type: string addr3: description: >- The third line of an address (if a third line is needed). type: string addr4: description: >- The fourth line of an address (if a fourth line is needed). type: string addr5: description: >- The fifth line of an address (if a fifth line is needed). type: string type: object customer_ref: description: >- `customer_ref` identifies a customer or customer job. If both `full_name` and `list_id` are provided, `full_name` is ignored. In SalesReceipt and ReceivePayment, it identifies who receives credit. In TimeTracking, it identifies who the time can be billed to and is required in TimeTrackingAdd when IsBillable is true. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object terms_ref: description: >- Refers to the payment terms associated with this entity. (This will be an item on the DateDrivenTerms or StandardTerms list.) If a `terms_ref` aggregate includes both `full_name` and `list_id`, `full_name` will be ignored. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object due_date: description: The date on which payment is due. format: date type: string credit_remaining_in_home_currency: description: >- The amount of the remaining credit, expressed in units of the current home currency. type: number subtotal: description: >- The total of all the credit-memo lines, before taxes are applied. (By contrast, a subtotal item (an ItemSubtotal object) gives only the total of the amounts in the lines that appear above it.) type: number sales_tax_total: description: The total amount of sales tax charged. type: number time_created: description: Time the object was created. format: date-time type: string edit_sequence: description: >- `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`. If your value is stale, the update is rejected to prevent overwriting newer changes. type: string sales_rep_ref: description: >- A sales representative must be on the Employee, Vendor, or Other Names list within QuickBooks. Sales representative’s names and initials appear on the Rep drop-down list on QuickBooks sales forms. A `sales_rep_ref` refers to a person on the SalesRep list. In a request, if a `sales_rep_ref` aggregate includes both `full_name` and `list_id`, `full_name` will be ignored. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object sales_tax_line_ret: not: anyOf: - required: - amount - rate_percent properties: account_ref: properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object amount: description: |- A monetary amount. Choose at most one of: `amount`, or `rate_percent`. type: number rate_percent: description: |- Indicates the price of something as a percent. Choose at most one of: `amount`, or `rate_percent`. type: number type: object class_ref: description: >- Use classes to categorize transactions (for example, by department, location, or work type). Class tracking is off by default in QuickBooks. A `class_ref` points to one class; if both `full_name` and `list_id` are provided, `full_name` is ignored. In InvoiceAdd, a header-level `class_ref` is applied to line items unless you override or clear it on individual lines. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object data_ext_ret: items: properties: data_ext_name: description: >- The name of the data extension. If this is a custom field, `data_ext_name` will be visible as a label in the QuickBooks user interface. Also because `owner_id` and `data_ext_name` together make the data extension unique, and because custom fields all have the same `owner_id` of zero, the `data_ext_name` must be a unique value among existing custom fields. type: string data_ext_type: description: >- The field’s data type, which corresponds to a qbXML data type. In an IDataExtDefAdd request object, if this is a custom field, `data_ext_type` must be detSTR255TYPE. enum: - AMTTYPE - DATETIMETYPE - INTTYPE - PERCENTTYPE - PRICETYPE - QUANTYPE - STR1024TYPE - STR255TYPE type: string data_ext_value: description: >- The data in this field. The maximum length of `data_ext_value` will depend on the `data_ext_type` of this data extension. For example, if `data_ext_type` is STR255TYPE, the maximum length of `data_ext_value` is 255 characters. If `data_ext_type` is STR1024TYPE, the maximum size of `data_ext_value` is 1KB. type: string owner_id: description: >- `owner_id` identifies who owns the data extension. Use 0 for QuickBooks custom fields that appear in the UI, or use a GUID for private extensions owned by an app. Keep private GUIDs confidential unless you intentionally share extensions across apps. If you do share them, both apps must use the same `owner_id` and `data_ext_name`, because that pair uniquely identifies the extension. type: string type: object type: array external_guid: description: Allows for the attachment of a user defined GUID value. type: string credit_remaining: description: Available credit. type: number ship_method_ref: description: >- A shipping method, for example, standard mail or overnight delivery. A `ship_method_ref` aggregate refers to an item on the ShipMethod list. In a request, if a `ship_method_ref` aggregate includes both `full_name` and `list_id`, `full_name` will be ignored. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object po_number: description: Purchase order number. type: string shipping_line_ret: properties: account_ref: properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object amount: description: A monetary amount. type: number type: object credit_memo_line_ret: description: >- Represents one line in the credit memo. Compare with CreditMemoGroupLine, which represents a previously defined group of lines in the credit memo. `credit_memo_line_ret` and `credit_memo_line_group_ret` combine: any number of each. items: not: anyOf: - required: - rate - rate_percent - required: - serial_number - lot_number properties: amount: description: A monetary amount. type: number class_ref: description: >- Use classes to categorize transactions (for example, by department, location, or work type). Class tracking is off by default in QuickBooks. A `class_ref` points to one class; if both `full_name` and `list_id` are provided, `full_name` is ignored. In InvoiceAdd, a header-level `class_ref` is applied to line items unless you override or clear it on individual lines. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object credit_card_txn_info: description: >- Contains data from the credit card transaction used in the payment. This data originates from a previous qbmsXML credit card transaction. The data following the element `credit_card_txn_input_info`” data is the data from the original qbmsXML request. The “`credit_card_txn_result_info`” is the data from the original qbmsXML response. properties: credit_card_txn_input_info: description: >- This contains data originally supplied in the QBMS transaction request. This information block shouldn’t be used in CreditMemo requests for QuickBooks 2007 and new versions. Instead, use the ARRefundCreditCard request. properties: commercial_card_code: description: >- This optional field is used only for Visa and Master Card commercial cards. There are three types of these cards: purchase, corporate, and business. Normally, special lower transaction fee rates apply when these cards are used and this field is filled out. If this field is left blank, then the usual (and higher) discount rate applies. type: string credit_card_address: description: >- The address associated with this credit card. type: string credit_card_number: description: >- Credit-card number for this customer or this payment. Beginning with qbXML spec 6.0 and QuickBooks 2007, you must mask the credit card number with lower case “x” and no dashes. For example, xxxxxxxxxxxx1234. type: string credit_card_postal_code: description: >- The postal code associated with the address for this credit card. type: string credit_card_txn_type: description: >- Indicates the QBMS transaction from which the current transaction data originated, for example, Charge, Authorization, Capture, Refund, VoiceAuthorization, or Void. enum: - Authorization - Capture - Charge - Refund - VoiceAuthorization type: string expiration_month: description: The month when the credit card expires. maximum: 12 minimum: 1 type: integer expiration_year: description: The year when the credit card expires. type: integer name_on_card: description: The name on the customer’s credit card. type: string transaction_mode: description: >- Indicates whether this transaction came from a card swipe (tmCardPresent) or not (tmCardNotPresent). enum: - CardNotPresent - CardPresent type: string type: object credit_card_txn_result_info: description: >- This contains data returned in the QBMS transaction response. This information block shouldn’t be used in CreditMemo requests for QuickBooks 2007 and new versions. Instead, use the ARRefundCreditCard request. properties: authorization_code: description: >- The authorization code is returned from the credit card processor to indicate that the charge will be paid by the card issuer. In a voice authorization request (CustomerCreditCardVoiceAuthRq), the authorization code is supplied by the card issuer over the telephone. type: string avs_street: description: >- This field contains the value avssPass if the street address supplied in the transaction request matches the customer’s address on file at the card issuer. It contains the value avssFail if there isn’t a match, or avssNotAvailable if the card issuer doesn’t support AVS. Note: This field was required in qbXML 4.1, but is optional in qbXML 5.0 and later. enum: - Fail - NotAvailable - Pass type: string avs_zip: description: >- This field contains the value avszPass if the customer postal ZIP code supplied in the transaction request matches the customer’s postal code recognized at the card issuer. It contains the value avszFail if there isn’t a match, or avszNotAvailable if the card issuer doesn’t support AVS. Note: This field was required in qbXML 4.1, but is optional in qbXML 5.0 and later. enum: - Fail - NotAvailable - Pass type: string card_security_code_match: description: >- This field contains the value Pass if the card security code supplied in the transaction request matches the card security code recognized for that credit card number at the card issuer. It contains the value Fail if there isn’t a match. enum: - Fail - NotAvailable - Pass type: string client_trans_id: description: >- This value is returned from QBMS transactions for future use by the QuickBooks Reconciliation feature. type: string credit_card_trans_id: description: >- This transaction ID is returned from the credit card processor. You should save this value for any possible QBMS SDK transaction requests that need it, for example, CustomerCreditCardTxnVoidRq, or CustomerCreditCardCaptureRq. type: string merchant_account_number: description: >- This is the QBMS account number of the merchant who is running the transaction using the customer’s credit card. It is returned from the transaction request and should be stored for subsequent transactions, such as using it in the QB SDK SalesReceiptAdd, ReceivePaymentAdd, ARRefundCreditCard requests to save the transaction data in QuickBooks. type: string payment_grouping_code: description: >- Internal code needed for the QuickBooks reconciliation feature, if integrating with QuickBooks. This value is returned in the QBMS response to a QBMS transaction request, and must be subsequently supplied by your application in the QB SDK ReceivePaymentAdd or SalesReceiptAdd request. type: integer payment_status: description: >- Indicates payment processing status as known by QuickBooks/QBMS integration state. `psCompleted` indicates confirmed success; `psUnknown` indicates status could not be definitively confirmed. enum: - Completed - Unknown type: string recon_batch_id: description: >- This value is returned by QBMS from the transaction request, and is used internally by the QuickBooks/QBMS Recon (reconcile) feature. You should save this value without modification and include it in the QB SDK SalesReceiptAdd or ReceivePaymentAdd requests if you want to save the transaction data in QuickBooks. type: string result_code: description: >- This contains the status code returned in the original QBMS transaction response. type: integer result_message: description: >- This contains the status message returned in the original QBMS transaction response. type: string txn_authorization_stamp: description: >- This value is used to support the credit card transaction Reconcile feature within QuickBooks. type: integer txn_authorization_time: description: >- Timestamp indicating the time in which the card processor authorized the transaction. format: date-time type: string type: object type: object data_ext_ret: items: properties: data_ext_name: description: >- The name of the data extension. If this is a custom field, `data_ext_name` will be visible as a label in the QuickBooks user interface. Also because `owner_id` and `data_ext_name` together make the data extension unique, and because custom fields all have the same `owner_id` of zero, the `data_ext_name` must be a unique value among existing custom fields. type: string data_ext_type: description: >- The field’s data type, which corresponds to a qbXML data type. In an IDataExtDefAdd request object, if this is a custom field, `data_ext_type` must be detSTR255TYPE. enum: - AMTTYPE - DATETIMETYPE - INTTYPE - PERCENTTYPE - PRICETYPE - QUANTYPE - STR1024TYPE - STR255TYPE type: string data_ext_value: description: >- The data in this field. The maximum length of `data_ext_value` will depend on the `data_ext_type` of this data extension. For example, if `data_ext_type` is STR255TYPE, the maximum length of `data_ext_value` is 255 characters. If `data_ext_type` is STR1024TYPE, the maximum size of `data_ext_value` is 1KB. type: string owner_id: description: >- `owner_id` identifies who owns the data extension. Use 0 for QuickBooks custom fields that appear in the UI, or use a GUID for private extensions owned by an app. Keep private GUIDs confidential unless you intentionally share extensions across apps. If you do share them, both apps must use the same `owner_id` and `data_ext_name`, because that pair uniquely identifies the extension. type: string type: object type: array desc: description: A descriptive text field. type: string inventory_site_location_ref: description: Location within the Inventory Site. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object inventory_site_ref: description: Site where inventory is located. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object is_taxable: type: boolean item_ref: description: >- `item_ref` may accept all item types or a restricted subset, depending on the request. Examples: PurchaseOrder and Bill do not allow discount or sales-tax items; VehicleMileageAdd requires a service or other-charge item; BillingRateAdd requires a service item. If both `full_name` and `list_id` are provided, `full_name` is ignored. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object lot_number: description: >- The lot number of the asset. Choose at most one of: `serial_number`, or `lot_number`. type: string other1: description: >- Other, Other1, and Other2 are built-in transaction custom fields. Other is transaction-level; Other1 and Other2 are line-level. These fields are always available through the SDK and do not require DataExtDef setup. Template labels in the UI can be renamed, but SDK names remain fixed as Other, Other1, and Other2. type: string other2: description: >- Other, Other1, and Other2 are built-in transaction custom fields. Other is transaction-level; Other1 and Other2 are line-level. These fields are always available through the SDK and do not require DataExtDef setup. Template labels in the UI can be renamed, but SDK names remain fixed as Other, Other1, and Other2. type: string override_uom_set_ref: description: >- When you modify a transaction line to change the unit of measure used in that line, you use this aggregate to specify the UOM set within which you are choosing an available unit of measure. The “override” here refers to the unit within the set, not the UOM Set itself, which you can’t change or override–the UOM set that can be set or changed only in the item itself via an Item Mod request. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object quantity: description: >- On transaction lines, QuickBooks can derive one value from the other two among Quantity, Rate, and Amount. If you supply Quantity and Amount, QuickBooks calculates Rate. If you supply Quantity and Rate, QuickBooks calculates Amount. type: number rate: description: >- If you specify both Rate and Amount in a request, the Rate you provide will be ignored, and you will receive a warning. If you specify both Quantity and Amount in an Add request, QuickBooks will use them to calculate Rate. (Rate, Amount, and Quantity can’t be cleared.) Choose at most one of: `rate`, or `rate_percent`. type: number rate_percent: description: |- Indicates the price of something as a percent. Choose at most one of: `rate`, or `rate_percent`. type: number sales_tax_code_ref: description: >- `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. If sales tax is disabled, QuickBooks assigns the default non-taxable code. If both `full_name` and `list_id` are provided in `sales_tax_code_ref`, `full_name` is ignored. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object serial_number: description: >- The serial number of the asset. Choose at most one of: `serial_number`, or `lot_number`. type: string service_date: description: >- Indicates the date on which the QuickBooks user performs the service for the customer. format: date type: string tax_amount: type: number txn_line_id: description: >- Identification number of the transaction line. (`txn_line_id` is supported as of v2.0 of the SDK. With qbXML v1.0 and v1.1, `txn_line_id` is always returned as zero.) If you need to add a new transaction line in a transaction Mod request, you can do so by setting the `txn_line_id` to -1. type: string unit_of_measure: description: >- In a transaction line item, the name of the unit of measure selected from within the item’s available units. If the company file is enabled only for single unit of measure per item, this must be the base unit! type: string type: object type: array memo: description: >- The memo doesn’t print on the credit memo, but does appear in the account register and the customer register. type: string currency_ref: description: >- A 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. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object txn_date: description: >- The 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. format: date type: string item_sales_tax_ref: description: >- An ItemSalesTax entry represents one tax rate paid to one tax agency. Use it when a transaction needs a single tax calculation. For multi-rate scenarios, use a sales-tax group instead. If both `full_name` and `list_id` are provided for `item_sales_tax_ref`, `list_id` is used. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object is_to_be_emailed: description: >- When enabled, QuickBooks validates the customer email at runtime before sending. If no valid email is available, the request fails. type: boolean template_ref: description: >- QuickBooks templates specify how to print certain transactions. A template query returns the names of all templates that have been defined in QuickBooks. A `template_ref` element refers to one of these templates. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object ar_account_ref: description: >- `ar_account_ref` points to an Accounts Receivable account. If both `full_name` and `list_id` are provided, `full_name` is ignored. properties: full_name: description: >- `full_name` (along with `list_id`) is a way to identify a list object. The `full_name` is the name prefixed by the names of each ancestor, for example Jones:Kitchen:Cabinets. `full_name` values aren’t case-sensitive. type: string list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string type: object exchange_rate: description: >- `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. If your home currency is USD and internet access is available, rates can be downloaded in the QuickBooks UI via Lists > Currency > Activities > Download Latest Exchange Rates. type: number total_amount: description: Subtotal plus `sales_tax_total`. type: number ship_date: description: The date when the product was, or will be, shipped. format: date type: string title: CreditMemoRet type: object - oneOf: - properties: list_id: description: >- `list_id` and `full_name` both identify a list object. QuickBooks assigns `list_id` when the object is created. `list_id` values are unique within a list family, not across the company file: customers, vendors, employees and other names share one sequence, every item type shares another, and each other list has its own. type: string required: - list_id title: ListID type: object - properties: owner_id: description: >- `owner_id` identifies who owns the data extension. Use 0 for QuickBooks custom fields that appear in the UI, or use a GUID for private extensions owned by an app. Keep private GUIDs confidential unless you intentionally share extensions across apps. If you do share them, both apps must use the same `owner_id` and `data_ext_name`, because that pair uniquely identifies the extension. type: string required: - owner_id title: OwnerID type: object - properties: txn_id: description: >- `txn_id` is the unique QuickBooks identifier for a transaction. Use it to reference that transaction in later requests. `txn_id` values are transaction-specific and should not be reused across unrelated transaction types. type: string required: - txn_id title: TxnID type: object properties: edit_sequence: description: >- `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`. If your value is stale, the update is rejected to prevent overwriting newer changes. type: string external_guid: description: Allows for the attachment of a user defined GUID value. type: string txn_number: description: An identifying number for this transaction. type: integer title: ErrorRecovery type: object message: description: >- QuickBooks' own status message, carried through when there is no data to show for an otherwise successful request (a query that matched nothing, say). type: string status: const: success warning: description: >- Present only when QuickBooks answered with a `Warn` severity: it carried the request out, and `data` is what it saved or found, but it has something to say about it. For example code `530` with the message `The field "Memo" is not supported by this implementation.` means the record was saved without that field, so an add or update that comes back with a `warning` may not have saved everything it sent. Absent on a plain success and on an error. properties: code: description: QuickBooks' own statusCode. The stable thing to branch on. type: integer message: description: >- QuickBooks' own statusMessage, such as which field it did not support. type: string required: - code type: object required: - status title: Success type: object - properties: error: properties: code: description: QuickBooks' own statusCode. The stable thing to branch on. examples: - 1030 - 3000 - 3040 - 3070 - 3120 - 3140 - 3150 - 3170 - 3171 - 3175 - 3176 - 3200 - 3210 - 3220 - 3250 - 3260 - 3263 type: - integer - 'null' current: description: >- The record as it stands in QuickBooks, shaped as a success's `data`, when QuickBooks sent it with the refusal, as it does with `stale_edit_sequence` (3200). Nothing was changed, and `current.edit_sequence` is the record's current one: re-apply your change and send it again with that `edit_sequence`. Absent when QuickBooks sent no record; then query the record first. type: object message: description: QuickBooks' own statusMessage. type: string type: description: >- A stable name for `code`, when QuBeSync recognises it. Absent otherwise: coverage widens over time, so treat this as a hint and branch on `code` if you need certainty. * `unsupported_request` (1030): The QuickBooks this connection talks to does not support this request. * `invalid_object_id` (3000): A ListID or TxnID in the request is not a valid id at all; the message names the field. * `invalid_amount` (3040): QuickBooks couldn't read an amount: it was written without its two decimals, such as 40 for 40.00, which the qbXML schema allows and QuickBooks doesn't. The message names the value and the field. * `string_too_long` (3070): A text value is longer than QuickBooks allows for that field; the message names the field. * `object_not_found` (3120): The request named a record by its ListID or TxnID, and the company file has no such record. * `invalid_reference` (3140): A reference names a record the company file does not have; the message says which list (Account, Item, Customer...). * `missing_element` (3150): QuickBooks requires an element the request left out; the message names it. * `cannot_modify` (3170): QuickBooks refused to save the change to an existing record. * `closing_date_modify` (3171): The transaction is dated on or before the company's closing date, which is password-protected. * `in_use` (3175): The record is in use, so it cannot be added, changed or deleted right now. * `locked` (3176): Someone has the record open in QuickBooks, or QuickBooks is in a single-user mode (such as the Adjust Quantity/Value on Hand window) that blocks changes. * `stale_edit_sequence` (3200): The edit_sequence sent is not the record's current one: it changed in QuickBooks after you read it. * `invalid_value` (3210): A field's value is not one QuickBooks accepts; the message names the field and the value. * `not_authorized` (3220): QuickBooks refused the request: no permission for it, or the feature is turned off in this company file. * `feature_not_enabled` (3250): The feature is turned off in this company file, or this edition of QuickBooks does not have it. * `insufficient_permission` (3260): The permission level QuickBooks granted does not allow this action. * `read_only_access` (3263): The application has read-only access to this company file, so it cannot add or change records. What each means and how to handle it: [Error handling](https://docs.qubesync.com/error_handling#quickbooks-said-no). enum: - unsupported_request - invalid_object_id - invalid_amount - string_too_long - object_not_found - invalid_reference - missing_element - cannot_modify - closing_date_modify - in_use - locked - stale_edit_sequence - invalid_value - not_authorized - feature_not_enabled - insufficient_permission - read_only_access type: string type: object status: const: error required: - status - error title: Error type: object Error: description: >- What a refused request answers with. The one key is errors, and its shape says what went wrong: a sentence when the endpoint explains the refusal in words (a parameter the operation does not take, a key already taken, a run that has already ended); an object with detail, and a code when there is one, when the request named nothing that exists or may not do what it asked (402, 403, 404, and a CLI session's 401), or an answer to a run's question was refused (the decisions endpoint's 400, 409 and 422, which always carry a code to branch on); an object of fields, each a list of messages, when a record failed validation and nothing was saved; a list of {path, message} problems when a submitted document or input fails validation. A request without a usable API key gets a 401 Basic challenge with the plain-text body Unauthorized, not JSON. properties: errors: oneOf: - example: 'unknown parameter: "emial"' title: A sentence type: string - properties: code: example: read_only_session type: string detail: example: Not Found type: string required: - detail title: Detail and code type: object - additionalProperties: items: type: string type: array example: webhook_url: - may not contain a username or password title: Field by field type: object - items: properties: message: example: is required type: string path: example: input.customer type: string required: - path - message type: object title: Located problems type: array required: - errors type: object headers: IdempotentReplayed: description: >- `true` when the call repeated an earlier call's `Idempotency-Key`: this is what that call created, as it is now, and nothing new was queued. Absent otherwise. schema: enum: - 'true' type: string responses: BadRequest: content: application/json: example: errors: 'unknown parameter: "emial"' schema: $ref: '#/components/schemas/Error' description: >- A parameter the operation does not take, or a value it cannot use. Nothing was queued. Unauthorized: content: text/plain: example: Unauthorized schema: type: string description: >- No usable API key. The key is Basic auth, so the answer is the challenge, with the plain-text body Unauthorized rather than JSON. headers: WWW-Authenticate: schema: example: Basic realm="Application" type: string SandboxPaused: content: application/json: example: errors: detail: >- Sandbox access is paused for this organization because the sandbox period expired and the organization does not currently have both active billing and a recent production connection. Please request an extension if you're still working on your integration or contact support if you have questions. schema: $ref: '#/components/schemas/Error' description: >- A sandbox app whose organization's sandbox access is paused. Nothing was queued. NotFound: content: application/json: example: errors: detail: Not Found schema: $ref: '#/components/schemas/Error' description: Nothing by that id, or it belongs to another app. UnprocessableEntity: content: application/json: example: errors: webhook_url: - may not contain a username or password schema: $ref: '#/components/schemas/Error' description: >- A field failed validation, field by field, and nothing was queued: a `webhook_url` that is not an absolute http or https URL, carries a username or password, is longer than 2048 characters, or (in production) points at localhost or a private address. An `Idempotency-Key` that isn't 1 to 255 printable ASCII characters, or that was already used for a different request, is refused in a sentence naming the header. securitySchemes: apiKey: description: Use your app's API key as the username, and leave the password blank scheme: basic type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.