Skill: Customer Upsert

The Customer Upsert skill creates new customer records, updates existing ones, or performs an upsert (create if not found, update if exists) in QuickBooks Online. This is the primary skill for managing customer data.

Parameters

Parameter	Type	Required	Description
action	string	Yes	The operation to perform: create, update, or upsert.
display_name	string	Yes (for create/upsert)	The customer’s display name. Must be unique in QuickBooks.
given_name	string	No	Customer’s first name.
family_name	string	No	Customer’s last name.
company_name	string	No	Associated company name.
primary_email_addr	string	No	Primary email address.
primary_phone	object	No	Primary phone number. Object with free_form_number field.
mobile_phone	object	No	Mobile phone number. Object with free_form_number field.
alternate_phone	object	No	Alternate phone number. Object with free_form_number field.
bill_addr	object	No	Billing address. Object with line1, line2, city, country_sub_division_code (state), postal_code, country fields.
ship_addr	object	No	Shipping address. Same structure as bill_addr.
id	string	Yes (for update)	QuickBooks customer ID. Required when action is update.
sync_token	string	Yes (for update)	QuickBooks sync token for optimistic concurrency. Required when action is update.

Caution

When updating a customer, you must provide the current id and sync_token. These values come from a prior Query Customer call. If the sync_token does not match (because someone else updated the record), the update will fail with a conflict error.

Action modes

Action	Behavior
create	Creates a new customer. Fails if display_name already exists.
update	Updates an existing customer. Requires id and sync_token.
upsert	Searches by display_name. If found, updates. If not found, creates.

Example usage

Creating a new customer:

“Add a new customer: Jane Smith at Acme Corp, email jane@acme.com, billing address 123 Main St, Springfield, IL 62701.”

The agent would invoke this skill with:

• action: create
• display_name: Jane Smith
• given_name: Jane
• family_name: Smith
• company_name: Acme Corp
• primary_email_addr: jane@acme.com
• bill_addr: { "line1": "123 Main St", "city": "Springfield", "country_sub_division_code": "IL", "postal_code": "62701" }

Updating an existing customer:

“Update Acme Corp’s email to billing@acme.com.”

The agent would first query the customer to get the id and sync_token, then invoke this skill with:

• action: update
• id: 12345
• sync_token: 2
• primary_email_addr: billing@acme.com

Note

The agent always confirms with the user before executing create or update operations. This behavior is built into the recommended agent instructions for any agent using write skills.

Response structure

The skill returns the created or updated customer record, including:

• Id — the QuickBooks customer ID.
• SyncToken — the new sync token (incremented after an update).
• All customer fields reflecting the current state after the operation.

API endpoint

POST /api/quickbooks/v1.0/customer-upsert

---

Related skills: Query Customer | Search Invoices