Skip to main content
POST
Create item inventory assembly

Authorizations

Authorization
string
header
required

Use your app's API key as the username, and leave the password blank

Headers

Idempotency-Key
string

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.

Required string length: 1 - 255
Pattern: ^[\x20-\x7E]+$

Path Parameters

connection_id
string<uuid>
required

The connection (a customer's QuickBooks company file) this request is queued for.

Query Parameters

webhook_url
string<uri>

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.

Maximum string length: 2048

Body

application/json
name
string
required

Name is the case-insensitive short name of a list object (without ancestors). It must be unique within its hierarchy scope. Hierarchical lists can reuse the same Name in different branches because full_name remains distinct.

asset_account_ref
object

Refers to the account QuickBooks uses to track the current value of the company’s inventory. (The AccountType of this account will be FixedAsset, OtherAsset, or OtherCurrentAsset.) In a request, if an asset_account_ref aggregate includes both full_name and list_id, full_name will be ignored.

bar_code
object

Barcode reference information.

build_point
number

The build notification point. The QuickBooks user will receive a notification when quantity_on_hand plus quantity_on_order falls below build_point.

class_ref
object

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.

cogs_account_ref
object

Refers to the account that QuickBooks uses to track the original cost of goods that are eventually sold. (The AccountType of this account will be CostOfGoodsSold.) In a request, if a cogs_account_ref aggregate includes both full_name and list_id, full_name will be ignored.

external_guid
string

Allows for the attachment of a user defined GUID value.

include_ret_element
enum<string>[]
Available options:
AssetAccountRef,
AverageCost,
BarCodeValue,
BuildPoint,
COGSAccountRef,
ClassRef,
DataExtRet,
EditSequence,
ExternalGUID,
FullName,
IncomeAccountRef,
IsActive,
IsTaxIncluded,
ItemInventoryAssemblyLine,
ListID,
ManufacturerPartNumber,
Max,
Name,
OwnerID,
ParentRef,
PrefVendorRef,
PurchaseCost,
PurchaseDesc,
PurchaseTaxCodeRef,
QuantityOnHand,
QuantityOnOrder,
QuantityOnSalesOrder,
SalesDesc,
SalesPrice,
SalesTaxCodeRef,
Sublevel,
TimeCreated,
TimeModified,
TxnID,
TxnNumber,
UnitOfMeasureSetRef
income_account_ref
object

Refers to an income account. If an income_account_ref aggregate includes both full_name and list_id, full_name will be ignored.

inventory_date
string<date>

The date when an item was converted into an inventory item from some other type of item.

is_active
boolean

If is_active is true, this object is currently enabled for use by QuickBooks. The default value is true.

is_tax_included
boolean

For future use with international versions of QuickBooks.

item_inventory_assembly_line
object[]
manufacturer_part_number
string

The part number used by the manufacturer of the item.

max
number

Maximum number of items in inventory.

parent_ref
object

A reference to the list object that is one level above this one. For example, an inventory item with the full_name of GermanCars:Mercedes-Benz:CL500I99AA might have a parent object with the full_name of GermanCars:Mercedes-Benz. In a request, if a parent_ref aggregate includes both full_name and list_id, full_name will be ignored.

pref_vendor_ref
object

The preferred vendor for this item. If a pref_vendor_ref aggregate includes both full_name and list_id, full_name will be ignored.

purchase_cost
number

Amount that the QuickBooks user expects to pay when ordering or buying this item, or the amount that was actually paid for this item.

purchase_desc
string

Description that appears in the Description column of checks, bills, credit card charges, and item receipts (when an item is reordered). For a fixed asset, a description of the item as it was when it was purchased.

purchase_tax_code_ref
object

Account used for taxes on purchases in CA or UK.

quantity_on_hand
number

The number of these items in inventory. quantity_on_hand times average_cost is total_value in an inventory item list. To change the quantity_on_hand for an item, you would have to use InventoryAdjustmentAdd not an ItemInventoryMod.

request_id
string

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.

sales_desc
string

Appears in the Description column of a sales form when the QuickBooks user sells this item. For a fixed asset, describes the sale of the asset (for accounting purposes).

sales_price
number

Price charged for this item.

sales_tax_code_ref
object

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.

total_value
number

The total value of this inventory. If total_value is included, quantity_on_hand must also be included and must be greater than zero. If both quantity_on_hand and purchase_cost are included, then total_value will be set to quantity_on_hand times purchase_cost, regardless of what total_value is explicitly set to.

unit_of_measure_set_ref
object

The unit of measure set consists of a base unit and 0-n related units.

Callbacks

POST
{$request.query.webhook_url}answered

Body

application/json

POSTed to webhook_url as JSON, signed with X-QUBE-Signature (t=<timestamp>,v1=<hex HMAC-SHA256 of "<timestamp>.<raw body>" with your app's webhook secret>).

app_id
string<uuid>
required

Your app's id.

app_name
string
required
error
object | null
required

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.

id
string<uuid>
required

The request's id, as the 201 returned it. For an iterated query, every page carries the first page's id here.

page_request_id
string<uuid>
required

This page's own id. Equal to id except on later pages of an iterated query.

response_json
Success · object
required

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.

sandbox
boolean
required

Whether the app is a sandbox app.

state
enum<string>
required

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.

Available options:
response_received,
error,
retryable,
timed_out,
discarded
timestamp
integer
required

Unix seconds; the same t the signature covers.

iteration_state
enum<string>

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.

Available options:
not_applicable,
continue,
done,
max_sandbox_iterations_reached

Present only with response_xml_omitted.

page
integer | null

The page number, when iterated.

response_xml
string | null

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.

response_xml_omitted
boolean

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.

Response

2XX

Received. Anything else is retried with backoff for about 8 hours.

Response

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.

data
object
required