Customers resource

Endpoints, filters and the create and update fields for customers in the Wirebook API, with curl, TypeScript and Python examples.

What it is

People or companies you sell to (QuickBooks Customer list).

Customers live in the connected QuickBooks Desktop company file. Every call names the file with the X-End-User-Id header, and every field name below is the JSON key you send and receive. Behaviour on this page is validated against the QuickBooks Web Connector simulator and not yet against a real QuickBooks Desktop install. The acceptance run on a Windows rig is a launch step.

Endpoints

GET https://wirebook.buffersoltech.com/v1/qbd/customers lists customers. Filters: name, active, modifiedSince, modifiedUntil, plus limit (1 to 100, default 25) and cursor. The response has data, hasMore, nextCursor and cursorExpiresAt.

GET https://wirebook.buffersoltech.com/v1/qbd/customers/{id} returns one record by its listId.

POST https://wirebook.buffersoltech.com/v1/qbd/customers creates a record and returns 201 with the created object. Send an Idempotency-Key header on every write.

POST https://wirebook.buffersoltech.com/v1/qbd/customers/{id} updates a record. Send the revisionNumber you read, and a stale one returns 409.

Create fields

Fields for POST https://wirebook.buffersoltech.com/v1/qbd/customers. Unknown fields are rejected with 400 invalid_request and the JSON path of the first problem. Lengths are the QuickBooks limits.

text

field                   type     required  max length
name                    string   yes       41
isActive                boolean  no
parentRef               object   no
parentRef.listId        string   no        36
parentRef.fullName      string   no        209
companyName             string   no        41
firstName               string   no        25
lastName                string   no        25
billAddress             object   no
billAddress.addr1       string   no        41
billAddress.addr2       string   no        41
billAddress.addr3       string   no        41
billAddress.city        string   no        31
billAddress.state       string   no        21
billAddress.postalCode  string   no        13
billAddress.country     string   no        31
shipAddress             object   no
shipAddress.addr1       string   no        41
shipAddress.addr2       string   no        41
shipAddress.addr3       string   no        41
shipAddress.city        string   no        31
shipAddress.state       string   no        21
shipAddress.postalCode  string   no        13
shipAddress.country     string   no        31
phone                   string   no        21
email                   string   no        1023
termsRef                object   no
termsRef.listId         string   no        36
termsRef.fullName       string   no        209

Update fields

Fields for POST https://wirebook.buffersoltech.com/v1/qbd/customers/{id}. The listId goes in the URL, not in the body. revisionNumber is required: it is the value you read last, and it protects against overwriting a change made in QuickBooks. Every other field is optional and only the fields you send change.

text

field                   type     required  max length
revisionNumber          string   yes
name                    string   no        41
isActive                boolean  no
parentRef               object   no
parentRef.listId        string   no        36
parentRef.fullName      string   no        209
companyName             string   no        41
firstName               string   no        25
lastName                string   no        25
billAddress             object   no
billAddress.addr1       string   no        41
billAddress.addr2       string   no        41
billAddress.addr3       string   no        41
billAddress.city        string   no        31
billAddress.state       string   no        21
billAddress.postalCode  string   no        13
billAddress.country     string   no        31
shipAddress             object   no
shipAddress.addr1       string   no        41
shipAddress.addr2       string   no        41
shipAddress.addr3       string   no        41
shipAddress.city        string   no        31
shipAddress.state       string   no        21
shipAddress.postalCode  string   no        13
shipAddress.country     string   no        31
phone                   string   no        21
email                   string   no        1023
termsRef                object   no
termsRef.listId         string   no        36
termsRef.fullName       string   no        209

Example with curl

Create a record with the required fields. Replace the key and the end user id with your own.

bash

curl -X POST https://wirebook.buffersoltech.com/v1/qbd/customers \
  -H "Authorization: Bearer sk_test_..." \
  -H "X-End-User-Id: acme-42" \
  -H "Idempotency-Key: customers-create-1" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Builders"}'

Example with TypeScript

Typed with the models generated from the same field specs. create returns the record, or a Queued marker if QuickBooks has not answered yet.

import { Wirebook } from "@wirebook/sdk";

const qb = new Wirebook({ apiKey: process.env.WIREBOOK_API_KEY! }).forUser("acme-42");

const created = await qb.qbd.customers.create({
  "name": "Acme Builders"
});

for await (const row of qb.qbd.customers.iterate({ limit: 100 })) {
  console.log(row);
}

await qb.qbd.customers.update("<listId>", {
  "revisionNumber": "1700000000",
  "name": "Updated"
});

Example with Python

The Python SDK takes the same JSON keys, as typed dictionaries.

python

import os
from wirebook import Wirebook

qb = Wirebook(os.environ["WIREBOOK_API_KEY"]).for_user("acme-42")

created = qb.qbd.customers.create({
    "name": "Acme Builders",
})

for row in qb.qbd.customers.iterate(limit=100):
    print(row)

qb.qbd.customers.update("<listId>", {
    "revisionNumber": "1700000000",
    "name": "Updated",
})

Waiting for QuickBooks

A request waits for QuickBooks to answer for 55 seconds. If QuickBooks has not answered by then, the API returns 202 with a request id and a Location header, and you poll GET /v1/requests/{id}. Send Prefer: respond-async to get the 202 straight away without waiting. The company file must be open and polling, see Troubleshooting.

If a write times out after it was sent, its state becomes outcome_unknown. Query by RefNumber before you retry, and do not retry blindly.