Create customer
create_customerAdds a customer, or a job under one: set parent_ref to the customer and the job's full_name becomes Parent:Job. name is required. QuickBooks keeps customers, vendors, employees and other names in one name space, so a name any of them already uses fails with 3100 name_in_use. The ensure workflow template adds the customer only if it isn't there yet, and on a clash finds out what holds the name and asks.
The customer_add wrapper from qbXML is also accepted. Returns the v2 request to send, and the webhook payload QuickBooks' answer arrives in (this operation's response_json: its data shape and the status codes to handle).
Possible errors (error.code / error.type; the call result explains each): 1030 unsupported_request, 3000 invalid_object_id, 3040 invalid_amount, 3070 string_too_long, 3100 name_in_use, 3120 object_not_found, 3140 invalid_reference, 3150 missing_element, 3175 in_use, 3176 locked, 3180 cannot_save, 3210 invalid_value, 3220 not_authorized, 3231 request_not_processed, 3250 feature_not_enabled, 3260 insufficient_permission, 3261 personal_data_access_denied, 3262 payroll_subscription_required, 3263 read_only_access, 3264 merchant_services_subscription_required, 3270 missing_posting_account
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"name": "<name>"
},
"name": "create_customer"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cc | No | Email address that would be carbon copied or CC. | |
| fax | No | Fax number. | |
| name | Yes | Name is the case-insensitive short name of a list object (without ancestors). It must be unique within its hierarchy scope. | |
| No | E-mail address. | ||
| notes | No | Not supported. | |
| pager | No | ||
| phone | No | The telephone number. | |
| mobile | No | ||
| suffix | No | ||
| contact | No | The name of a contact person for a customer or vendor. | |
| contacts | No | ||
| job_desc | No | A short job description for a sub-customer; used in reports. | |
| print_as | No | ||
| alt_phone | No | A telephone number given as an alternative to Phone. | |
| class_ref | No | Use classes to categorize transactions (for example, by department, location, or work type). Class tracking is off by default in QuickBooks. | |
| is_active | No | If `is_active` is true, this object is currently enabled for use by QuickBooks. The default value is true. | |
| job_title | No | The job title of a customer, vendor, employee, or person on the “other names” list. | |
| last_name | No | The last name of a customer, vendor, employee, or person on the “other names” list. | |
| terms_ref | No | Refers to the payment terms associated with this entity. (This will be an item on the DateDrivenTerms or StandardTerms list.) | |
| first_name | No | The first name of a customer, vendor, employee, or person on the “other names” list. | |
| job_status | No | `job_status` Status information about a sub-customer; used in reports. | |
| parent_ref | No | A reference to the list object that is one level above this one. | |
| request_id | No | 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`. | |
| salutation | No | A formal reference, such as Mr. or Dr., that precedes a name. | |
| alt_contact | No | The name of an alternate contact person for a vendor, customer, or “other name” entry. | |
| middle_name | No | The middle name of a customer, vendor, employee, or person on the “other names” list. | |
| bill_address | No | 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). | |
| company_name | No | The name of the QuickBooks user’s business, as specified in QuickBooks. `company_name` and Address are used on invoices, checks, and other forms. | |
| credit_limit | No | 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. | |
| currency_ref | No | 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. | |
| job_end_date | No | The date on which work for a sub-customer was completed; used in reports. | |
| job_type_ref | No | 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. | |
| open_balance | No | The opening balance of this customer’s account. A positive number indicates money owed by the customer. | |
| ship_address | No | 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). | |
| external_guid | No | Allows for the attachment of a user defined GUID value. | |
| include_qbxml | No | Also return the qbXML this compiles to, for debugging. Not part of the v2 request. | |
| resale_number | No | The customer’s resale number, if they have one. This number won’t affect reports or sales tax calculations. | |
| sales_rep_ref | No | 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. | |
| account_number | No | Account numbers appear in the QuickBooks chart of accounts, Account fields, and reports and graphs. | |
| job_start_date | No | The date on which work for a sub-customer was started; used in reports. | |
| delivery_method | No | ||
| price_level_ref | No | 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. | |
| ship_to_address | No | ||
| additional_notes | No | ||
| credit_card_info | No | Customer’s credit-card information. | |
| customer_type_ref | No | Customer types allow business owners to categorize customers in ways that are meaningful for their businesses. | |
| open_balance_date | No | The date of the opening balance for this customer. | |
| sales_tax_country | No | Country that sales tax is collected for. | |
| item_sales_tax_ref | No | 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. | |
| sales_tax_code_ref | No | `sales_tax_code_ref` points to the sales-tax code used for an item or customer context. QuickBooks includes default TAX and NON codes, and a code can be deleted only when nothing references it. | |
| include_ret_element | No | ||
| additional_contact_ref | No | ||
| job_projected_end_date | No | The date on which work for a sub-customer is expected to be complete; used in reports. | |
| tax_registration_number | No | Tax registration number used in CA and UK. | |
| is_statement_with_parent | No | ||
| preferred_delivery_method | No | Preference for how invoices are delivered. | |
| preferred_payment_method_ref | No | 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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Replace {connection_id} with the customer's connection. | |
| body | Yes | The JSON body: the arguments you passed. | |
| qbxml | No | The qbXML it compiles to. Only with include_qbxml. | |
| method | Yes | ||
| headers | Yes | Send with the request. Resent unchanged when no 201 came back, it answers with the request already queued. | |
| webhook | Yes | JSON Schema of the payload POSTed to webhook_url once QuickBooks answers, with this operation's response_json (data shape and status codes). |