Use cases

Here are use cases that demonstrate how to use the Custom Fields resource.

The information on this page applies to QuickBooks Online Advanced, Plus, and Essentials, and goes through the operations supported by the API. For specific information on the capabilities of each product, see Feature support by product.

App integration

The following figure provides an overview of how to integrate the Custom Fields API with your app.

qbo/docs/workflows/create-custom-fields/custom-field-integration-diagram.png
qbo/docs/workflows/create-custom-fields/custom-field-integration-diagram.png

x

Use case 1: Add a custom field to an invoice
Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
  {
      "Line": [
          {
              "Amount": 200.00,
              "DetailType": "SalesItemLineDetail",
              "SalesItemLineDetail": {
                  "ItemRef": {
                      "value": "1",
                      "name": "Services"
                  }
              }
          }
      ],
      "CustomField": [
          {
              "DefinitionId": "1",
              "StringValue": "my custom value",
          }
      ],
      "CustomerRef": {
          "value": "1"
      }
  }
Response

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
  {
      "Invoice": {
          "AllowIPNPayment": false,
          "AllowOnlinePayment": false,
          "AllowOnlineCreditCardPayment": false,
          "AllowOnlineACHPayment": false,
          "domain": "QBO",
          "sparse": false,
          "Id": "801",
          "SyncToken": "0",
          "MetaData": {
              "CreateTime": "2024-05-29T23:22:07-07:00",
              "LastModifiedByRef": {
                  "value": "9130347769252966"
              },
              "LastUpdatedTime": "2024-05-29T23:22:07-07:00"
          },
          "CustomField": [
              {
                  "DefinitionId": "1",
                  "Name": "sales1",
                  "Type": "StringType",
                  "StringValue": "my custom value"
              }
          ],
          "TxnDate": "2024-05-29",
          "CurrencyRef": {
              "value": "USD",
              "name": "United States Dollar"
          },
          "ExchangeRate": 1,
          "LinkedTxn": [],
          "Line": [
              {
                  "Id": "1",
                  "LineNum": 1,
                  "Amount": 200.00,
                  "DetailType": "SalesItemLineDetail",
                  "SalesItemLineDetail": {
                      "ItemRef": {
                          "value": "1",
                          "name": "Sales"
                      },
                      "ItemAccountRef": {
                          "value": "1",
                          "name": "Sales"
                      },
                      "TaxCodeRef": {
                          "value": "NON"
                      },
                      "TaxClassificationRef": {
                          "value": "EUC-99990201-V1-00020000"
                      }
                  }
              },
              {
                  "Amount": 200.00,
                  "DetailType": "SubTotalLineDetail",
                  "SubTotalLineDetail": {}
              }
          ],
          "TxnTaxDetail": {
              "TxnTaxCodeRef": {
                  "value": "8"
              },
              "TotalTax": 0,
              "TaxLine": [
                  {
                      "Amount": 0,
                      "DetailType": "TaxLineDetail",
                      "TaxLineDetail": {
                          "TaxRateRef": {
                              "value": "4"
                          },
                          "PercentBased": true,
                          "TaxPercent": 1,
                          "NetAmountTaxable": 0
                      }
                  }
              ]
          },
          "CustomerRef": {
              "value": "1",
              "name": "John"
          },
          "ShipFromAddr": {
              "Id": "1274",
              "Line1": "2500 Garcia Avenue",
              "Line2": "Mountain View, CA  94043 US"
          },
          "DueDate": "2024-06-28",
          "TotalAmt": 200.00,
          "HomeTotalAmt": 200.00,
          "ApplyTaxAfterDiscount": false,
          "PrintStatus": "NeedToPrint",
          "EmailStatus": "NotSet",
          "Balance": 200.00,
          "HomeBalance": 200.00,
          "TaxExemptionRef": {}
      },
      "time": "2024-05-29T23:22:06.843-07:00"
  }
Use case 2: Enable custom fields for the Customer entity
Request

1
2
3
4
5
6
7
8
9
  {
      "DisplayName": "Customer-01",
      "CustomField": [
          {
              "DefinitionId": "540344",
              "StringValue": "CF-CustomerType"
          }
      ]
  }
Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
  {
      "Customer": {
          "Taxable": false,
          "Job": false,
          "BillWithParent": false,
          "Balance": 0,
          "BalanceWithJobs": 0,
          "CurrencyRef": {
              "value": "USD",
              "name": "United States Dollar"
          },
          "PreferredDeliveryMethod": "None",
          "IsProject": false,
          "domain": "QBO",
          "sparse": false,
          "Id": "4",
          "SyncToken": "0",
          "MetaData": {
              "CreateTime": "2024-06-29T19:12:52-07:00",
              "LastUpdatedTime": "2024-06-29T19:12:52-07:00"
          },
          "CustomField": [
              {
                  "DefinitionId": "540344",
                  "Name": "cf-05",
                  "Type": "StringType",
                  "StringValue": "CF-CustomerType"
              }
          ],
          "FullyQualifiedName": "Customer-01",
          "DisplayName": "Customer-01",
          "PrintOnCheckName": "Customer-01",
          "Active": true
      },
      "time": "2024-06-29T19:12:51.593-07:00"
  }