Purchase orders resource
Endpoints, filters and the create and update fields for purchase-orders in the Wirebook API, with curl, TypeScript and Python examples.
What it is
Orders you place with vendors (QuickBooks PurchaseOrder transaction).
Purchase orders 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/purchase-orders lists purchase-orders. Filters: vendor, refNumber, modifiedSince, includeLines, plus limit (1 to 100, default 25) and cursor. The response has data, hasMore, nextCursor and cursorExpiresAt.
GET https://wirebook.buffersoltech.com/v1/qbd/purchase-orders/{id} returns one record by its txnId.
POST https://wirebook.buffersoltech.com/v1/qbd/purchase-orders 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/purchase-orders/{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/purchase-orders. Unknown fields are rejected with 400 invalid_request and the JSON path of the first problem. Lengths are the QuickBooks limits.
field type required max length
vendorRef object yes
vendorRef.listId string no 36
vendorRef.fullName string no 209
classRef object no
classRef.listId string no 36
classRef.fullName string no 209
shipToEntityRef object no
shipToEntityRef.listId string no 36
shipToEntityRef.fullName string no 209
templateRef object no
templateRef.listId string no 36
templateRef.fullName string no 209
txnDate date (YYYY-MM-DD) no
refNumber string no 11
vendorAddress object no
vendorAddress.addr1 string no 41
vendorAddress.addr2 string no 41
vendorAddress.addr3 string no 41
vendorAddress.city string no 31
vendorAddress.state string no 21
vendorAddress.postalCode string no 13
vendorAddress.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
termsRef object no
termsRef.listId string no 36
termsRef.fullName string no 209
dueDate date (YYYY-MM-DD) no
expectedDate date (YYYY-MM-DD) no
shipMethodRef object no
shipMethodRef.listId string no 36
shipMethodRef.fullName string no 209
memo string no 4095
isToBePrinted boolean no
isToBeEmailed boolean no
lines[] array no
lines[].itemRef object yes
lines[].itemRef.listId string no 36
lines[].itemRef.fullName string no 209
lines[].desc string no 4095
lines[].quantity number no
lines[].unitOfMeasure string no 31
lines[].rate number no
lines[].classRef object no
lines[].classRef.listId string no 36
lines[].classRef.fullName string no 209
lines[].amount number no
lines[].customerRef object no
lines[].customerRef.listId string no 36
lines[].customerRef.fullName string no 209Update fields
Fields for POST https://wirebook.buffersoltech.com/v1/qbd/purchase-orders/{id}. The txnId 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.
Every line you send carries txnLineId. Send the txnLineId of an existing line to change it, or "-1" to add a new line.
field type required max length
revisionNumber string yes
vendorRef object no
vendorRef.listId string no 36
vendorRef.fullName string no 209
classRef object no
classRef.listId string no 36
classRef.fullName string no 209
shipToEntityRef object no
shipToEntityRef.listId string no 36
shipToEntityRef.fullName string no 209
templateRef object no
templateRef.listId string no 36
templateRef.fullName string no 209
txnDate date (YYYY-MM-DD) no
refNumber string no 11
vendorAddress object no
vendorAddress.addr1 string no 41
vendorAddress.addr2 string no 41
vendorAddress.addr3 string no 41
vendorAddress.city string no 31
vendorAddress.state string no 21
vendorAddress.postalCode string no 13
vendorAddress.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
termsRef object no
termsRef.listId string no 36
termsRef.fullName string no 209
dueDate date (YYYY-MM-DD) no
expectedDate date (YYYY-MM-DD) no
shipMethodRef object no
shipMethodRef.listId string no 36
shipMethodRef.fullName string no 209
memo string no 4095
isToBePrinted boolean no
isToBeEmailed boolean no
lines[] array no
lines[].txnLineId string yes
lines[].itemRef object no
lines[].itemRef.listId string no 36
lines[].itemRef.fullName string no 209
lines[].desc string no 4095
lines[].quantity number no
lines[].unitOfMeasure string no 31
lines[].rate number no
lines[].classRef object no
lines[].classRef.listId string no 36
lines[].classRef.fullName string no 209
lines[].amount number no
lines[].customerRef object no
lines[].customerRef.listId string no 36
lines[].customerRef.fullName string no 209Example with curl
Create a record with the required fields. Replace the key and the end user id with your own.
curl -X POST https://wirebook.buffersoltech.com/v1/qbd/purchase-orders \
-H "Authorization: Bearer sk_test_..." \
-H "X-End-User-Id: acme-42" \
-H "Idempotency-Key: purchase-orders-create-1" \
-H "Content-Type: application/json" \
-d '{"vendorRef":{"listId":"80000001-1"}}'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.purchaseOrders.create({
"vendorRef": {
"listId": "80000001-1"
}
});
for await (const row of qb.qbd.purchaseOrders.iterate({ limit: 100 })) {
console.log(row);
}
await qb.qbd.purchaseOrders.update("<txnId>", {
"revisionNumber": "1700000000",
"refNumber": "Updated",
"lines": [
{
"txnLineId": "-1",
"quantity": 1
}
]
});Example with Python
The Python SDK takes the same JSON keys, as typed dictionaries.
import os
from wirebook import Wirebook
qb = Wirebook(os.environ["WIREBOOK_API_KEY"]).for_user("acme-42")
created = qb.qbd.purchase_orders.create({
"vendorRef": {
"listId": "80000001-1",
},
})
for row in qb.qbd.purchase_orders.iterate(limit=100):
print(row)
qb.qbd.purchase_orders.update("<txnId>", {
"revisionNumber": "1700000000",
"refNumber": "Updated",
"lines": [
{
"txnLineId": "-1",
"quantity": 1,
},
],
})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.