Skip to main content
PUT
Update customer

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
​
list_id
string
required

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.

​
edit_sequence
string
required

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.

​
additional_notes_mod
object[]
​
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.

​
ship_address
object

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.

​
mobile
string
​
bill_address
object

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.

​
job_projected_end_date
string<date>

The date on which work for a sub-customer is expected to be complete; used in reports. The Job- elements (job_desc, job_end_date, job_projected_end_date, job_start_date, and job_status) correspond to the fields in the Job Info tab of the Edit Job window in QuickBooks.

​
contacts_mod
object[]
​
delivery_method
enum<string>
Available options:
Email,
Fax,
Print
​
fax
string

Fax number.

​
company_name
string

The name of the QuickBooks user’s business, as specified in QuickBooks. company_name and Address are used on invoices, checks, and other forms. (LegalCompanyName and LegalAddress, on the other hand, are used on a company’s tax forms and pay stubs.)

​
ship_to_address
object[]
​
preferred_payment_method_ref
object

Refers to a PaymentMethod object. In a request, if a preferred_payment_method_ref aggregate includes both full_name and list_id, full_name will be ignored.

​
contact
string

The name of a contact person for a customer or vendor.

​
alt_contact
string

The name of an alternate contact person for a vendor, customer, or “other name” entry.

​
price_level_ref
object

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.

​
job_status
enum<string>

job_status Status information about a sub-customer; used in reports. The Job- elements (job_desc, job_end_date, job_projected_end_date, job_start_date, and job_status) correspond to the fields in the Job Info tab of the Edit Job window in QuickBooks.

Available options:
Awarded,
Closed,
InProgress,
None,
NotAwarded,
Pending
​
customer_type_ref
object

Customer types allow business owners to categorize customers in ways that are meaningful for their businesses. For example, a customer type might indicate which industry a customer represents, or which part of the country a customer is in. A customer_type_ref aggregate refers to one of the types on the CustomerType list.

​
job_start_date
string<date>

The date on which work for a sub-customer was started; used in reports. The Job- elements (job_desc, job_end_date, job_projected_end_date, job_start_date, and job_status) correspond to the fields in the Job Info tab of the Edit Job window in QuickBooks.

​
credit_limit
number

Set and returned as a positive number that indicates a customer’s or vendor’s credit limit. If no value has been defined, there is no credit limit.

​
job_title
string

The job title of a customer, vendor, employee, or person on the “other names” list.

​
name
string

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.

​
terms_ref
object

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.

​
email
string

E-mail address.

​
credit_card_info
object

Customer’s credit-card information.

​
salutation
string

A formal reference, such as Mr. or Dr., that precedes a name.

​
is_statement_with_parent
boolean
​
sales_rep_ref
object

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.

​
phone
string

The telephone number.

​
job_desc
string

A short job description for a sub-customer; used in reports. The Job- elements (job_desc, job_end_date, job_projected_end_date, job_start_date, and job_status) correspond to the fields in the Job Info tab of the Edit Job window in QuickBooks.

​
job_type_ref
object

Job type can be used to separate jobs into any categories that are meaningful to the business. A job_type_ref aggregate refers to a job type on the JobType list. In a request, if a job_type_ref aggregate includes both full_name and list_id, full_name will be ignored.

​
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.

​
alt_phone
string

A telephone number given as an alternative to Phone.

​
print_as
string
​
middle_name
string

The middle name of a customer, vendor, employee, or person on the “other names” list.

​
last_name
string

The last name of a customer, vendor, employee, or person on the “other names” list.

​
cc
string

Email address that would be carbon copied or CC.

​
suffix
string
​
currency_ref
object

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.

​
sales_tax_country
enum<string>

The country that sales tax is collected for.

Available options:
Australia,
Canada,
UK,
US
​
item_sales_tax_ref
object

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.

​
additional_contact_ref
object[]
​
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.

​
job_end_date
string<date>

The date on which work for a sub-customer was completed; used in reports. The Job- elements (job_desc, job_end_date, job_projected_end_date, job_start_date, and job_status) correspond to the fields in the Job Info tab of the Edit Job window in QuickBooks.

​
is_active
boolean

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

​
pager
string
​
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.

​
tax_registration_number
string

The tax registration number used in CA and UK.

​
first_name
string

The first name of a customer, vendor, employee, or person on the “other names” list.

​
resale_number
string

The customer’s resale number, if they have one. This number won’t affect reports or sales tax calculations.

​
notes
string

Not supported.

​
include_ret_element
enum<string>[]
Available options:
AccountNumber,
AdditionalContactRef,
AdditionalNotesRet,
AltContact,
AltPhone,
Balance,
BillAddress,
BillAddressBlock,
Cc,
ClassRef,
CompanyName,
Contact,
ContactsRet,
CreditCardInfo,
CreditLimit,
CurrencyRef,
CustomerTypeRef,
DataExtRet,
DeliveryMethod,
EditSequence,
Email,
ExternalGUID,
Fax,
FirstName,
FullName,
IsActive,
IsStatementWithParent,
ItemSalesTaxRef,
JobDesc,
JobEndDate,
JobProjectedEndDate,
JobStartDate,
JobStatus,
JobTitle,
JobTypeRef,
LastName,
ListID,
MiddleName,
Mobile,
Name,
Notes,
OwnerID,
Pager,
ParentRef,
Phone,
PreferredDeliveryMethod,
PreferredPaymentMethodRef,
PriceLevelRef,
PrintAs,
ResaleNumber,
SalesRepRef,
SalesTaxCodeRef,
SalesTaxCountry,
Salutation,
ShipAddress,
ShipAddressBlock,
ShipToAddress,
Sublevel,
Suffix,
TaxRegistrationNumber,
TermsRef,
TimeCreated,
TimeModified,
TotalBalance,
TxnID,
TxnNumber
​
account_number
string

Account numbers appear in the QuickBooks chart of accounts, Account fields, and reports and graphs. If the IsUsingAccountNumber preference is false (that is, if the QuickBooks user has the account numbers Preference turned off), you can still set account numbers through the SDK, but the numbers won’t be visible in the user interface.

​
preferred_delivery_method
enum<string>

Preference for how invoices are delivered.

Available options:
Email,
Fax,
None

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
​
links
object

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