Use case

Here is a use cases that demonstrates the basics of how to use the Dimensions API.

Use case: Create a transaction with dimension

Use the Accounting REST API to create a invoice transaction and send DefinitionId with values from Step 1 below. This example creates an invoice with dimensions.

Step 1: Use appFoundationsCustomDimensionDefinitions (query) with pagination in the GraphQL API to read the Dimension Definition ID.

Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
  query ActiveCustomDimensionDefinitionsQuery {
      appFoundationsActiveCustomDimensionDefinitions (
          first: 5
          after: null
          last: null
          before: null
      ) {
          edges {
              node {
                  ...CustomDimensionDefinitionAttributes
              }
          }
      }
  }

  fragment CustomDimensionDefinitionAttributes on AppFoundations_CustomDimensionDefinition {
      id
      label
      active
  }

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
  {
      "data": {
          "appFoundationsActiveCustomDimensionDefinitions": {
              "edges": [
                  {
                      "node": {
                          "id": "1000000003",
                          "label": "Dimension #1",
                          "active": true
                      }
                  },
                  {
                      "node": {
                          "id": "1000000006",
                          "label": "Dimension #2",
                          "active": true
                      }
                  },
                  {
                      "node": {
                          "id": "1000000009",
                          "label": "Residential",
                          "active": true
                      }
                  },
                  {
                      "node": {
                          "id": "1000000053",
                          "label": "Commercial",
                          "active": true
                      }
                  },
                  {
                      "node": {
                          "id": "1000000056",
                          "label": "Ordinary",
                          "active": true
                      }
                  }
              ]
          }
      }
  }

Step 2: Next, fetch the Dimension Value ID based on the Dimension Definition ID fetched in the previous step.

Request

 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
  query GetActiveCustomDimensionValues (
      $first: Int,
      $after: String,
      $last: Int,
      $before: String,
      $filters: AppFoundations_ActiveCustomDimensionValuesFilterBy!
  ) {
      appFoundationsActiveCustomDimensionValues (
          first: $first
          after: $after
          last: $last
          before: $before
          filters: $filters
      ) {
          edges {
              node {
                  id
                  definitionId
                  label
                  active
                  parentId
                  fullyQualifiedLabel
                  level
              }
          }
          pageInfo {
              hasNextPage
              hasPreviousPage
              startCursor
              endCursor
          }
          totalCount
      }
  }

Variables

1
2
3
4
5
6
7
8
9
  { "first":null,
    "after":null,
    "last":null,
    "before":null,
    "filters": {
          "definitionId":"1000000009",
          "parentId":1000000010
      }
  }

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
  {
      "data": {
          "appFoundationsActiveCustomDimensionValues": {
              "edges": [
                  {
                      "node": {
                          "id": "1000000094",
                          "definitionId": "1000000009",
                          "label": "Site-1-a",
                          "active": true,
                          "parentId": "1000000010",
                          "fullyQualifiedLabel": "Site1:Site-1-a",
                          "level": 1
                      }
                  },
                  {
                      "node": {
                          "id": "1000000096",
                          "definitionId": "1000000009",
                          "label": "Site-1-b",
                          "active": true,
                          "parentId": "1000000010",
                          "fullyQualifiedLabel": "Site1:Site-1-b",
                          "level": 1
                      }
                  }
              ],
              "pageInfo": {
                  "hasNextPage": false,
                  "hasPreviousPage": false,
                  "startCursor": "0",
                  "endCursor": "1"
              },
              "totalCount": 2
          }
      }
  }

Step 3: Use the Accounting REST API resource to create an invoice. Use CustomExtensions to send dimension data. Attach the Dimension Definition ID to Key and the Dimension Value ID to Value.

Request

  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
103
104
105
106
107
      {
          "TxnDate": "2025-05-29",
          "CurrencyRef": {
              "value": "USD",
              "name": "United States Dollar"
          },
          "LinkedTxn": [],
          "Line": [
              {
                  "Id": "101101",
                  "LineNum": 1,
                  "Description": "Test1",
                  "Amount": 1.32,
                  "DetailType": "SalesItemLineDetail",
                  "CustomExtensions": [
                      {
                          "AssociatedValues": [
                              {
                                  "Value": "1000000010",
                                  "Key": "1000000009"
                              }
                          ],
                          "ExtensionType": "DIMENSION"
                      }
                  ],
                  "SalesItemLineDetail": {
                      "ItemRef": {
                          "value": "2"
                      },
                      "UnitPrice": 5.26,
                      "Qty": 0.25,
                      "ItemAccountRef": {
                          "value": "1",
                          "name": "Sales"
                      },
                      "ClassRef": {
                          "value": "758612"
                      }
                  }
              },
              {
                  "Amount": 1.31,
                  "DetailType": "SubTotalLineDetail",
                  "SubTotalLineDetail": {}
              },
              {
                  "Id": "101102",
                  "LineNum": 2,
                  "Description": "Test1",
                  "Amount": 1.32,
                  "DetailType": "SalesItemLineDetail",
                  "CustomExtensions": [
                      {
                          "AssociatedValues": [
                              {
                                  "Value": "1000000094",
                                  "Key": "1000000009"
                              }
                          ],
                          "ExtensionType": "DIMENSION"
                      }
                  ],
                  "SalesItemLineDetail": {
                      "ItemRef": {
                          "value": "2"
                      },
                      "UnitPrice": 5.26,
                      "Qty": 0.25,
                      "ItemAccountRef": {
                          "value": "1",
                          "name": "Sales"
                      },
                      "ClassRef": {
                          "value": "758612"
                      }
                  }
              },
              {
                  "Amount": 1.31,
                  "DetailType": "SubTotalLineDetail",
                  "SubTotalLineDetail": {}
              }
          ],
          "Tag": [],
          "CustomerRef": {
              "value": "1"
          },
          "CustomField": [
              {
                  "DefinitionId": "1000000011",
                  "StringValue": "Test"
              }
          ],
          "BillAddr": {
              "Id":"34168","Line1":"1000 Sutton Place",
              "City":"Horn Lake","Country":"USA","CountrySubDivisionCode":"MS","PostalCode":"38637"
          },
          "ShipAddr":{"Id":"34169","Line1":"1000 Sutton Place",
          "City":"Horn Lake","Country":"USA","CountrySubDivisionCode":"MS","PostalCode":"38637"},
          "FreeFormAddress": false,
          "SalesTermRef": {
              "value": "3",
              "name": "Net 30"
          },
          "TotalAmt": 1.32,
          "Balance": 1.32
      }

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
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
  {
      "Invoice": {
          "AllowIPNPayment": false,
          "AllowOnlinePayment": false,
          "AllowOnlineCreditCardPayment": true,
          "AllowOnlineACHPayment": true,
          "domain": "QBO",
          "sparse": false,
          "Id": "268",
          "SyncToken": "0",
          "MetaData": {
              "CreateTime": "2025-07-11T14:29:23-07:00",
              "LastModifiedByRef": {
                  "value": "9341453539654484"
          },
          "LastUpdatedTime": "2025-07-11T14:29:23-07:00"
      },
      "CustomField": [
          {
              "DefinitionId": "1",
              "Name": "Document Status",
              "Type": "StringType"
          }
      ],
      "TxnDate": "2025-05-29",
      "CurrencyRef": {
          "value": "USD",
          "name": "United States Dollar"
      },
      "LinkedTxn": [],
      "Line": [
          {
              "Id": "1",
              "LineNum": 1,
              "Description": "Test1",
              "Amount": 1.32,
              "DetailType": "SalesItemLineDetail",
              "SalesItemLineDetail": {
                  "ItemRef": {
                      "value": "2",
                      "name": "Hours"
                  },
                  "UnitPrice": 5.26,
                  "Qty": 0.25,
                  "ItemAccountRef": {
                      "value": "5",
                      "name": "Sales"
                  },
                  "TaxCodeRef": {
                      "value": "NON"
                  },
                  "TaxClassificationRef": {}
              },
              "CustomExtensions": [
                  {
                      "ExtensionType": "DIMENSION",
                      "AssociatedValues": [
                          {
                              "Key": "1000000009",
                              "Value": "1000000010"
                          }
                      ]
                  }
              ]
          },
          {
              "Id": "2",
              "LineNum": 2,
              "Description": "Test1",
              "Amount": 1.32,
              "DetailType": "SalesItemLineDetail",
              "SalesItemLineDetail": {
                  "ItemRef": {
                      "value": "2",
                      "name": "Hours"
                  },
                  "UnitPrice": 5.26,
                  "Qty": 0.25,
                  "ItemAccountRef": {
                      "value": "5",
                      "name": "Sales"
                  },
                  "TaxCodeRef": {
                      "value": "NON"
                  },
                  "TaxClassificationRef": {}
              },
              "CustomExtensions": [
                  {
                      "ExtensionType": "DIMENSION",
                      "AssociatedValues": [
                          {
                              "Key": "1000000009",
                              "Value": "1000000094"
                          }
                      ]
                  }
              ]
          },
          {
              "Amount": 2.64,
              "DetailType": "SubTotalLineDetail",
              "SubTotalLineDetail": {}
          }
      ],
      "TxnTaxDetail": {
          "TxnTaxCodeRef": {
              "value": "2"
          },
          "TotalTax": 0,
          "TaxLine": [
              {
                  "Amount": 0,
                  "DetailType": "TaxLineDetail",
                  "TaxLineDetail": {
                      "TaxRateRef": {
                          "value": "2"
                      },
                      "PercentBased": true,
                      "TaxPercent": 0,
                      "NetAmountTaxable": 0
                  }
              }
          ]
      },
      "CustomerRef": {
          "value": "1",
          "name": "King's Groceries1"
      },
      "BillAddr": {
          "Id": "406",
          "Line1": "1000 Sutton Place",
          "City": "Horn Lake",
          "Country": "USA",
          "CountrySubDivisionCode": "MS",
          "PostalCode": "38637"
      },
      "ShipAddr": {
          "Id": "407",
          "Line1": "1000 Sutton Place",
          "City": "Horn Lake",
          "Country": "USA",
          "CountrySubDivisionCode": "MS",
          "PostalCode": "38637"
      },
      "FreeFormAddress": false,
      "ShipFromAddr": {
          "Id": "408",
          "Line1": "2600 Marine Way",
          "Line2": "Mountain View, CA  94043-1126",
          "Line3": "USA"
      },
      "SalesTermRef": {
          "value": "3",
          "name": "Net 30"
      },
      "DueDate": "2025-06-28",
      "TotalAmt": 2.64,
      "ApplyTaxAfterDiscount": false,
      "PrintStatus": "NeedToPrint",
      "EmailStatus": "NotSet",
      "Balance": 2.64,
      "TaxExemptionRef": {}
      },
      "time": "2025-07-11T14:29:22.678-07:00"
  }