Customers

Customers are the entity the simulator models in the most depth: you create, read, update, deactivate and reactivate them, and every write is checked against the customer’s current SyncToken and the company’s name rules.

The shipped scenarios seed their customers from Id 1. Creating a customer stores it under the next Id after the highest one stored, so creating one never takes a seeded customer’s Id.

Create a customer

A POST …/customer with no Id creates a customer. The block below resets to an empty company first, so the new customer gets Id 1, then creates one and tries its name again:

R=4620816365320737870
curl -s -X POST "$RYSTIC_URL/_rystic/reset"
curl -s "$RYSTIC_URL/v3/company/$R/customer" -H 'Authorization: Bearer placeholder' -H 'Content-Type: application/json' -d '{"GivenName":"Maple","FamilyName":"Cafe"}' | jq -c '.Customer | {Id, DisplayName, SyncToken, Active}'
# -> {"Id":"1","DisplayName":"Maple Cafe","SyncToken":"0","Active":true}
curl -s "$RYSTIC_URL/v3/company/$R/customer" -H 'Authorization: Bearer placeholder' -H 'Content-Type: application/json' -d '{"DisplayName":" MAPLE CAFE "}' | jq -c '.Fault.Error[0] | {code, Message}'
# -> {"code":"6240","Message":"Duplicate Name Exists Error"}

The simulator assigns the Id, sets SyncToken to "0" and fills each field you leave out:

Creating a customer needs a DisplayName or at least one name part. The name parts are Title, GivenName, MiddleName, FamilyName and Suffix. The simulator joins the parts you send with spaces into the display name. With neither, it returns 400 6080.

Update a customer

Send the same route with Id and the customer’s current SyncToken, and its SyncToken goes up by one:

curl -s "$RYSTIC_URL/v3/company/$R/customer" -H 'Authorization: Bearer placeholder' -H 'Content-Type: application/json' -d '{"Id":"1","SyncToken":"0","sparse":true,"Notes":"Net 30"}' | jq -c '.Customer | {Id, Notes, SyncToken}'
# -> {"Id":"1","Notes":"Net 30","SyncToken":"1"}

With "sparse": true only the fields you send change; without it, every writable field the body leaves out is cleared. A SyncToken that is not current is refused (Idempotency), and so is an Id that matches no customer (Error format).

Deactivate and reactivate a customer

A sparse update with "Active": false deactivates the customer, and "Active": true reactivates it. There is no delete, and a deactivated customer still reads by Id:

curl -s "$RYSTIC_URL/v3/company/$R/customer" -H 'Authorization: Bearer placeholder' -H 'Content-Type: application/json' -d '{"Id":"1","SyncToken":"1","sparse":true,"Active":false}' | jq -c '.Customer | {Id, Active, SyncToken}'
# -> {"Id":"1","Active":false,"SyncToken":"2"}
curl -s "$RYSTIC_URL/v3/company/$R/customer/1" -H 'Authorization: Bearer placeholder' | jq -c '.Customer | {Id, DisplayName, Active}'
# -> {"Id":"1","DisplayName":"Maple Cafe","Active":false}

Names

DisplayName is unique among active customers, ignoring case and surrounding spaces. A clash returns 400 6240. A deactivated customer’s name is free to reuse.

The check runs only on a name you send. An update that sends no DisplayName, such as a reactivation, is not checked. So reactivating a customer whose name another customer has since taken leaves two active customers with one name. Whether QuickBooks refuses that reactivation is unconfirmed.

Read

GET …/customer/{customerId} reads a customer, active or not. Error format lists how a read refuses an Id.

Sub-customers

Creating or updating a customer keeps the ParentRef, Job and BillWithParent you send. The simulator doesn’t check that the parent exists and sets no RootCustomerRef; whether QuickBooks does either is unconfirmed.

Differs from QuickBooks: the simulator sets no Level and keeps FullyQualifiedName as the customer’s own name, where QuickBooks sets Level and builds FullyQualifiedName as Parent:Child.

Differs from QuickBooks: an update sets BalanceWithJobs to the customer’s own Balance, so updating quickbooks_job_hierarchy’s parent drops its jobs’ balances from it. QuickBooks’ BalanceWithJobs includes every sub-job’s open balance.

Request ids

A customer write stores its requestid but never replays it (Idempotency).

Tax codes

A customer you create has no DefaultTaxCodeRef. What the scenarios do not hold names the tax code and rate each scenario seeds.