Custom fields

QuickBooks Desktop custom fields (its "data extensions") come through the QBO CustomField array. They are read on every record that carries them, and written on Customer, Vendor, Employee, Item, Invoice, SalesReceipt, Estimate, CreditMemo and PurchaseOrder.

curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "https://api.tenkeybridge.com/v3/company/$REALM/invoice" \
  -d '{
        "CustomerRef": { "value": "8000004F-1767225600" },
        "Line": [{ "Amount": 100, "DetailType": "SalesItemLineDetail",
                   "SalesItemLineDetail": { "ItemRef": { "value": "80000012-1767225600" } } }],
        "CustomField": [{ "Name": "Sales Rep", "StringValue": "Pat Owner" }]
      }'

Rules

• Define the field in QuickBooks first. The gateway cannot create fields. The field must exist and be assigned to that record type, and is matched by Name (case-insensitive). Desktop has no numeric definition id, so DefinitionId is accepted on the wire but a CustomField with a DefinitionId and no Name is a 400.
• Strings only. Type is always StringType. A value may be at most 30 characters and may not be empty or blank; otherwise 400 with nothing written.
• Checked before anything is written. An unknown or unassigned field name is 400 CUSTOM_FIELD_UNKNOWN and the record is not created or changed.
• An update can carry only CustomField. The SyncToken is still checked (a stale one is 5010).
• Line-level custom fields are not written, only the record's header fields.
• Bill has none. In QuickBooks Enterprise 24 (verified live) a custom field is defined on a Customer, Vendor, Employee or Item and then appears on the transactions that use it; none is ever assigned to Bills. A CustomField on a Bill is therefore a 400 (CUSTOM_FIELD_UNKNOWN: not assigned to Bill records).
• New transactions inherit. A new Invoice, PurchaseOrder, etc. starts with its customer's, vendor's or item's field value, exactly as in QuickBooks. A CustomField in your request overrides it.

When a write half-succeeds

A custom field is saved by a second message, after the record itself. So there are two new outcomes, both 502:

Code	What happened	What to do
CUSTOM_FIELD_WRITE_FAILED	The record was saved, but one or more field values were not. The fault names the record Id, the fields that applied and the ones that failed.	Do not resend the create: it would duplicate the record. Update the record with only the failed CustomField entries.
CUSTOM_FIELD_READBACK_FAILED	Everything was written; reading it back failed.	Do not retry. GET the record.

In a batch these appear in the item's fault slot. A successful response is a fresh read of the record, so it shows the stored values and the new SyncToken.

Sandbox

The developer sandbox ships five fields to try this with.

See also

• The CustomField row on each entity in the compatibility matrix.
• Safe retries: send a requestid on writes you may retry.