@lunch-money/developer-docs 2.11.0-preview.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +65 -0
- package/docs/README.md +16 -0
- package/docs/amounts-and-balances.md +85 -0
- package/docs/currencies.md +277 -0
- package/docs/getting-started.md +104 -0
- package/docs/introduction.md +63 -0
- package/docs/pagination.md +517 -0
- package/docs/rate-limiting.md +335 -0
- package/docs/using-with-ai.md +103 -0
- package/manifest.json +225 -0
- package/package.json +32 -0
- package/v1/_assets.md +188 -0
- package/v1/_budget.md +256 -0
- package/v1/_categories.md +407 -0
- package/v1/_changelog.md +102 -0
- package/v1/_crypto.md +105 -0
- package/v1/_plaid_accounts.md +117 -0
- package/v1/_recurring_expenses.md +117 -0
- package/v1/_recurring_items.md +240 -0
- package/v1/_tags.md +41 -0
- package/v1/_transactions.md +648 -0
- package/v1/_user.md +39 -0
- package/v2/docs/changelog-visual.html +506 -0
- package/v2/docs/intro-to-v2.md +117 -0
- package/v2/docs/migration-guide.md +1143 -0
- package/v2/docs/version-history.md +381 -0
- package/v2/images/CopyCategoriesAndTags.png +0 -0
- package/v2/images/DemoData.png +0 -0
- package/v2/images/PasteBearer.png +0 -0
- package/v2/images/RequestAccessToken.png +0 -0
- package/v2/images/TestRequest.png +0 -0
- package/v2/images/bearer.png +0 -0
- package/v2/images/green_budget.png +0 -0
- package/v2/images/new_budget.png +0 -0
- package/v2/images/server-dropdown.png +0 -0
- package/v2/spec/lunch-money-api-v2.yaml +11779 -0
|
@@ -0,0 +1,648 @@
|
|
|
1
|
+
# Transactions
|
|
2
|
+
|
|
3
|
+
<aside class="notice">
|
|
4
|
+
This API (v1) will not progress to a generally available state. For new projects, we recommend using the <a href="/v2/docs#tag/transactions">v2 API</a>, which is in open alpha and actively maintained.
|
|
5
|
+
</aside>
|
|
6
|
+
|
|
7
|
+
## Transaction Object
|
|
8
|
+
|
|
9
|
+
| Attribute Name | Type | Nullable | Description |
|
|
10
|
+
| -------------------------- | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
11
|
+
| id | number | false | Unique identifier for transaction |
|
|
12
|
+
| date | string | false | Date of transaction in ISO 8601 format |
|
|
13
|
+
| payee | string | false | Name of payee. If recurring_id is not null, this field will show the payee of associated recurring expense instead of the original transaction payee |
|
|
14
|
+
| amount | string | false | Amount of the transaction in numeric format to 4 decimal places |
|
|
15
|
+
| currency | string | false | Three-letter lowercase currency code of the transaction in ISO 4217 format |
|
|
16
|
+
| to_base | number | false | The amount converted to the user's primary currency. If the multicurrency feature is not being used, to_base and amount will be the same. |
|
|
17
|
+
| category_id | number | true | Unique identifier of associated category (see Categories) |
|
|
18
|
+
| category_name | string | true | Name of category associated with transaction |
|
|
19
|
+
| category_group_id | number | true | Unique identifier of associated category group, if any |
|
|
20
|
+
| category_group_name | string | true | Name of category group associated with transaction, if any |
|
|
21
|
+
| is_income | boolean | false | Based on the associated category's property, denotes if transaction is treated as income |
|
|
22
|
+
| exclude_from_budget | boolean | false | Based on the associated category's property, denotes if transaction is excluded from budget |
|
|
23
|
+
| exclude_from_totals | boolean | false | Based on the associated category's property, denotes if transaction is excluded from totals |
|
|
24
|
+
| created_at | string | false | The date and time of when the transaction was created (in the ISO 8601 extended format). |
|
|
25
|
+
| updated_at | string | false | The date and time of when the transaction was last updated (in the ISO 8601 extended format). |
|
|
26
|
+
| status | string | true | One of the following: <ul> <li>cleared: User has reviewed the transaction</li><li>uncleared: User has not yet reviewed the transaction</li><li>pending: Imported transaction is marked as pending. This should be a temporary state.</li></ul> Note: special statuses for recurring items have been deprecated. |
|
|
27
|
+
| is_pending | boolean | false | Denotes if transaction is pending (not posted) |
|
|
28
|
+
| notes | string | true | User-entered transaction notes If recurring_id is not null, this field will be description of associated recurring expense |
|
|
29
|
+
| original_name | string | true | The transactions original name before any payee name updates. For synced transactions, this is the raw original payee name from your bank. |
|
|
30
|
+
| recurring_id | number | true | Unique identifier of associated recurring item, or null for non-recurring transactions |
|
|
31
|
+
| recurring_payee | string | true | The payee of associated recurring expense instead of the original transaction, or null for non-recurring transactions |
|
|
32
|
+
| recurring_description | string | true | Description of associated recurring item, or null for non-recurring transactions |
|
|
33
|
+
| recurring_cadence | string | true | Cadence of associated recurring item (one of `once a week`, `every 2 weeks`, `twice a month`, `monthly`, `every 2 months`, `every 3 months`, `every 4 months`, `twice a year`, `yearly`) , or null for non-recurring transactions |
|
|
34
|
+
| recurring_type | string | true | Type of associated recurring (one of `cleared`, `suggested`, `dismissed`), or null for non-recurring transactions |
|
|
35
|
+
| recurring_amount | string | true | Amount of associated recurring item in numeric format to 4 decimals, or null for non-recurring transactions |
|
|
36
|
+
| recurring_currency | number | true | Currency of associated recurring item, or null for non-recurring transactions |
|
|
37
|
+
| parent_id | number | true | Exists if this is a split transaction. Denotes the transaction ID of the original transaction. |
|
|
38
|
+
| has_children | boolean | false | True if this transaction is a parent transaction and is split into 2 or more other transactions |
|
|
39
|
+
| group_id | number | true | Exists if this transaction is part of a group. Denotes the parent’s transaction ID |
|
|
40
|
+
| is_group | boolean | false | True if this transaction represents a group of transactions. If so, amount and currency represent the totalled amount of transactions bearing this transaction’s id as their group_id. Amount is calculated based on the user’s primary currency. |
|
|
41
|
+
| asset_id | number | true | Unique identifier of associated manually-managed account (see Assets) Note: plaid_account_id and asset_id cannot both exist for a transaction |
|
|
42
|
+
| asset_institution_name | string | true | Institution name of associated manually-managed account |
|
|
43
|
+
| asset_name | string | true | Name of associated manually-managed account |
|
|
44
|
+
| asset_display_name | string | true | Display name of associated manually-managed account |
|
|
45
|
+
| asset_status | string | true | Status of associated manually-managed account (one of `active`, `closed`) |
|
|
46
|
+
| plaid_account_id | number | true | Unique identifier of associated Plaid account (see Plaid Accounts) Note: plaid_account_id and asset_id cannot both exist for a transaction |
|
|
47
|
+
| plaid_account_name | string | true | Name of associated Plaid account |
|
|
48
|
+
| plaid_account_mask | string | true | Mask of associated Plaid account |
|
|
49
|
+
| institution_name | string | true | Institution name of associated Plaid account |
|
|
50
|
+
| plaid_account_display_name | string | true | Display name of associated Plaid account |
|
|
51
|
+
| plaid_metadata | string | true | Metadata associated with imported transaction from Plaid |
|
|
52
|
+
| source | string | false | Source of the transaction (one of `api`, `csv`, `manual`,`merge`,`plaid`,`recurring`,`rule`,`user`) |
|
|
53
|
+
| display_name | string | false | Display name for payee for transaction based on whether or not it is linked to a recurring item. If linked, returns `recurring_payee` field. Otherwise, returns the `payee` field. |
|
|
54
|
+
| display_notes | string | true | Display notes for transaction based on whether or not it is linked to a recurring item. If linked, returns `recurring_notes` field. Otherwise, returns the `notes` field. |
|
|
55
|
+
| account_display_name | string | false | Display name for associated account (manual or Plaid). If this is a synced account, returns `plaid_account_display_name` or `asset_display_name`. |
|
|
56
|
+
| tags | Tag[] | false | Array of Tag objects |
|
|
57
|
+
| children | Transaction[] | true | This property exists only on a transaction with the `is_group` property set to `true`. On a grouped transaction, this will be an array of Transaction objects for the transactions that make up the group. These objects are slimmed down to the more essential fields, and contain an extra field called `formatted_date` that contains the date of transaction in ISO 8601 format |
|
|
58
|
+
| external_id | string | true | User-defined external ID for any manually-entered or imported transaction. External ID cannot be accessed or changed for Plaid-imported transactions. External ID must be unique by asset_id. Max 75 characters. |
|
|
59
|
+
| original_date | string | true | DEPRECATED |
|
|
60
|
+
| type | string | true | DEPRECATED |
|
|
61
|
+
| subtype | string | true | DEPRECATED |
|
|
62
|
+
| fees | string | true | DEPRECATED |
|
|
63
|
+
| price | string | true | DEPRECATED |
|
|
64
|
+
| quantity | string | true | DEPRECATED |
|
|
65
|
+
|
|
66
|
+
## Get All Transactions
|
|
67
|
+
|
|
68
|
+
Use this endpoint to retrieve all transactions between a date range.
|
|
69
|
+
|
|
70
|
+
> Example 200 Response
|
|
71
|
+
|
|
72
|
+
```json
|
|
73
|
+
{
|
|
74
|
+
"transactions": [
|
|
75
|
+
{
|
|
76
|
+
"id": 246946944,
|
|
77
|
+
"date": "2023-07-18",
|
|
78
|
+
"amount": "53.1900",
|
|
79
|
+
"currency": "usd",
|
|
80
|
+
"to_base": 53.19,
|
|
81
|
+
"payee": "Amazon",
|
|
82
|
+
"category_id": 315172,
|
|
83
|
+
"category_name": "Restaurants",
|
|
84
|
+
"category_group_id": 315358,
|
|
85
|
+
"category_group_name": "Food & Drink",
|
|
86
|
+
"is_income": false,
|
|
87
|
+
"exclude_from_budget": false,
|
|
88
|
+
"exclude_from_totals": false,
|
|
89
|
+
"created_at": "2023-09-09T08:43:05.875Z",
|
|
90
|
+
"updated_at": "2023-10-09T06:07:03.105Z",
|
|
91
|
+
"status": "cleared",
|
|
92
|
+
"is_pending": false,
|
|
93
|
+
"notes": null,
|
|
94
|
+
"original_name": null,
|
|
95
|
+
"recurring_id": null,
|
|
96
|
+
"recurring_payee": null,
|
|
97
|
+
"recurring_description": null,
|
|
98
|
+
"recurring_cadence": null,
|
|
99
|
+
"recurring_type": null,
|
|
100
|
+
"recurring_amount": null,
|
|
101
|
+
"recurring_currency": null,
|
|
102
|
+
"parent_id": 225508713,
|
|
103
|
+
"has_children": false,
|
|
104
|
+
"group_id": null,
|
|
105
|
+
"is_group": false,
|
|
106
|
+
"asset_id": null,
|
|
107
|
+
"asset_institution_name": null,
|
|
108
|
+
"asset_name": null,
|
|
109
|
+
"asset_display_name": null,
|
|
110
|
+
"asset_status": null,
|
|
111
|
+
"plaid_account_id": 76602,
|
|
112
|
+
"plaid_account_name": "Amazon Whole Foods Visa",
|
|
113
|
+
"plaid_account_mask": "6299",
|
|
114
|
+
"institution_name": "Chase",
|
|
115
|
+
"plaid_account_display_name": "Amazon Whole Foods Visa",
|
|
116
|
+
"plaid_metadata": null,
|
|
117
|
+
"plaid_category": null,
|
|
118
|
+
"source": null,
|
|
119
|
+
"display_name": "Amazon",
|
|
120
|
+
"display_notes": null,
|
|
121
|
+
"account_display_name": "Amazon Whole Foods Visa",
|
|
122
|
+
"tags": [
|
|
123
|
+
{
|
|
124
|
+
"name": "Amazon",
|
|
125
|
+
"id": 76543
|
|
126
|
+
}
|
|
127
|
+
],
|
|
128
|
+
"external_id": null
|
|
129
|
+
},
|
|
130
|
+
{
|
|
131
|
+
"id": 246946943,
|
|
132
|
+
"date": "2023-07-18",
|
|
133
|
+
"amount": "12.2100",
|
|
134
|
+
"currency": "usd",
|
|
135
|
+
"to_base": 12.21,
|
|
136
|
+
"payee": "Frelard Tamales",
|
|
137
|
+
"category_id": 315172,
|
|
138
|
+
"category_name": "Restaurants",
|
|
139
|
+
"category_group_id": 315358,
|
|
140
|
+
"category_group_name": "Food & Drink",
|
|
141
|
+
"is_income": false,
|
|
142
|
+
"exclude_from_budget": false,
|
|
143
|
+
"exclude_from_totals": false,
|
|
144
|
+
"created_at": "2023-09-09T08:43:05.818Z",
|
|
145
|
+
"updated_at": "2023-10-09T06:07:03.529Z",
|
|
146
|
+
"status": "cleared",
|
|
147
|
+
"is_pending": false,
|
|
148
|
+
"notes": null,
|
|
149
|
+
"original_name": null,
|
|
150
|
+
"recurring_id": null,
|
|
151
|
+
"recurring_payee": null,
|
|
152
|
+
"recurring_description": null,
|
|
153
|
+
"recurring_cadence": null,
|
|
154
|
+
"recurring_type": null,
|
|
155
|
+
"recurring_amount": null,
|
|
156
|
+
"recurring_currency": null,
|
|
157
|
+
"parent_id": 225588844,
|
|
158
|
+
"has_children": false,
|
|
159
|
+
"group_id": null,
|
|
160
|
+
"is_group": true,
|
|
161
|
+
"asset_id": null,
|
|
162
|
+
"asset_institution_name": null,
|
|
163
|
+
"asset_name": null,
|
|
164
|
+
"asset_display_name": null,
|
|
165
|
+
"asset_status": null,
|
|
166
|
+
"plaid_account_id": 54174,
|
|
167
|
+
"plaid_account_name": "Amex -11005",
|
|
168
|
+
"plaid_account_mask": "1005",
|
|
169
|
+
"institution_name": "American Express",
|
|
170
|
+
"plaid_account_display_name": "Amex Plat",
|
|
171
|
+
"plaid_metadata": null,
|
|
172
|
+
"plaid_category": null,
|
|
173
|
+
"source": null,
|
|
174
|
+
"display_name": "Frelard Tamales",
|
|
175
|
+
"display_notes": null,
|
|
176
|
+
"account_display_name": "Amex Plat",
|
|
177
|
+
"tags": [],
|
|
178
|
+
"children": [
|
|
179
|
+
{
|
|
180
|
+
"id": 246946948,
|
|
181
|
+
"payee": "Child Transaction One",
|
|
182
|
+
"amount": "-33.6000",
|
|
183
|
+
"currency": "cad",
|
|
184
|
+
"date": "2023-08-10",
|
|
185
|
+
"formatted_date": "2023-09-10",
|
|
186
|
+
"notes": null,
|
|
187
|
+
"asset_id": 7409,
|
|
188
|
+
"plaid_account_id": null,
|
|
189
|
+
"to_base": -33.6
|
|
190
|
+
},
|
|
191
|
+
{
|
|
192
|
+
"id": 246946948,
|
|
193
|
+
"payee": "Child Transaction Two",
|
|
194
|
+
"amount": "-33.6000",
|
|
195
|
+
"currency": "cad",
|
|
196
|
+
"date": "2023-08-10",
|
|
197
|
+
"formatted_date": "2023-09-10",
|
|
198
|
+
"notes": null,
|
|
199
|
+
"asset_id": 7409,
|
|
200
|
+
"plaid_account_id": null,
|
|
201
|
+
"to_base": -33.6
|
|
202
|
+
}
|
|
203
|
+
]
|
|
204
|
+
"external_id": null
|
|
205
|
+
}
|
|
206
|
+
],
|
|
207
|
+
"has_more": true
|
|
208
|
+
}
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
> Example 404 Response
|
|
212
|
+
|
|
213
|
+
```json
|
|
214
|
+
{ "error": "Both start_date and end_date must be specified." }
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
Returns list of Transaction objects and a `has_more` indicator. If no query parameters are set, this endpoint will return transactions for the current calendar month (see `start_date` and `end_date`)
|
|
218
|
+
|
|
219
|
+
### HTTP Request
|
|
220
|
+
|
|
221
|
+
`GET https://api.lunchmoney.dev/v1/transactions`
|
|
222
|
+
|
|
223
|
+
### Query Parameters
|
|
224
|
+
|
|
225
|
+
| Parameter | Type | Required | Default | Description |
|
|
226
|
+
| ----------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
227
|
+
| tag_id | number | false | - | Filter by tag. Only accepts IDs, not names. |
|
|
228
|
+
| recurring_id | number | false | - | Filter by recurring expense |
|
|
229
|
+
| plaid_account_id | number | false | - | Filter by Plaid account |
|
|
230
|
+
| category_id | number | false | - | Filter by category. Will also match category groups. |
|
|
231
|
+
| asset_id | number | false | - | Filter by asset |
|
|
232
|
+
| is_group | boolean | false | - | Filter by group (returns transaction groups) |
|
|
233
|
+
| status | string | false | - | Filter by status (Can be `cleared` or `uncleared`. Note: special statuses for recurring items have been deprecated.) |
|
|
234
|
+
| start_date | string | false | - | Denotes the beginning of the time period to fetch transactions for. Defaults to beginning of current month. Required if end_date exists. Format: YYYY-MM-DD. |
|
|
235
|
+
| end_date | string | false | - | Denotes the end of the time period you'd like to get transactions for. Defaults to end of current month. Required if start_date exists. Format: YYYY-MM-DD. |
|
|
236
|
+
| debit_as_negative | boolean | false | false | Pass in true if you’d like expenses to be returned as negative amounts and credits as positive amounts. Defaults to false. |
|
|
237
|
+
| pending | boolean | false | false | Pass in true if you’d like to include imported transactions with a pending status. |
|
|
238
|
+
| offset | number | false | - | Sets the offset for the records returned |
|
|
239
|
+
| limit | number | false | 1000 | Sets the maximum number of records to return. |
|
|
240
|
+
| group_id | number | false | - | DEPRECATED (Use [GET /v1/transactions-group](#get-transaction-group) instead) |
|
|
241
|
+
|
|
242
|
+
## Get Single Transaction
|
|
243
|
+
|
|
244
|
+
Use this endpoint to retrieve details about a specific transaction by ID.
|
|
245
|
+
|
|
246
|
+
> Example 200 Response
|
|
247
|
+
|
|
248
|
+
```json
|
|
249
|
+
{
|
|
250
|
+
"id": 480887173,
|
|
251
|
+
"date": "2023-11-29",
|
|
252
|
+
"amount": "-14.1800",
|
|
253
|
+
"currency": "usd",
|
|
254
|
+
"to_base": -14.18,
|
|
255
|
+
"payee": "Walmart",
|
|
256
|
+
"category_id": 315295,
|
|
257
|
+
"category_name": "Health, Medical",
|
|
258
|
+
"category_group_id": 315357,
|
|
259
|
+
"category_group_name": "Personal",
|
|
260
|
+
"is_income": false,
|
|
261
|
+
"exclude_from_budget": false,
|
|
262
|
+
"exclude_from_totals": false,
|
|
263
|
+
"created_at": "2023-11-30T22:10:57.820Z",
|
|
264
|
+
"updated_at": "2023-11-30T23:59:56.587Z",
|
|
265
|
+
"status": "cleared",
|
|
266
|
+
"is_pending": false,
|
|
267
|
+
"notes": null,
|
|
268
|
+
"original_name": "Walmart",
|
|
269
|
+
"recurring_id": null,
|
|
270
|
+
"recurring_payee": null,
|
|
271
|
+
"recurring_description": null,
|
|
272
|
+
"recurring_cadence": null,
|
|
273
|
+
"recurring_type": null,
|
|
274
|
+
"recurring_amount": null,
|
|
275
|
+
"recurring_currency": null,
|
|
276
|
+
"parent_id": null,
|
|
277
|
+
"has_children": null,
|
|
278
|
+
"group_id": 481307164,
|
|
279
|
+
"is_group": false,
|
|
280
|
+
"asset_id": null,
|
|
281
|
+
"asset_institution_name": null,
|
|
282
|
+
"asset_name": null,
|
|
283
|
+
"asset_display_name": null,
|
|
284
|
+
"asset_status": null,
|
|
285
|
+
"plaid_account_id": 54174,
|
|
286
|
+
"plaid_account_name": "Amex 1002",
|
|
287
|
+
"plaid_account_mask": "1005",
|
|
288
|
+
"institution_name": "American Express",
|
|
289
|
+
"plaid_account_display_name": "Amex Plat",
|
|
290
|
+
"plaid_metadata": "{\"account_id\":\"fMKfypkyRXSXvpJor4vPTg6OP7wD4afmEjv6N\",\"account_owner\":\"1005\",\"amount\":-14.18,\"authorized_date\":\"2023-11-28\",\"authorized_datetime\":null,\"category\":[\"Shops\",\"Supermarkets and Groceries\"],\"category_id\":\"19047000\",\"check_number\":null,\"counterparties\":[{\"confidence_level\":\"VERY_HIGH\",\"entity_id\":\"O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM\",\"logo_url\":\"https://plaid-merchant-logos.plaid.com/walmart_1100.png\",\"name\":\"Walmart\",\"type\":\"merchant\",\"website\":\"walmart.com\"}],\"date\":\"2023-11-29\",\"datetime\":null,\"iso_currency_code\":\"USD\",\"location\":{\"address\":null,\"city\":null,\"country\":null,\"lat\":null,\"lon\":null,\"postal_code\":null,\"region\":null,\"store_number\":null},\"logo_url\":\"https://plaid-merchant-logos.plaid.com/walmart_1100.png\",\"merchant_entity_id\":\"O5W5j4dN9OR3E6ypQmjdkWZZRoXEzVMz2ByWM\",\"merchant_name\":\"Walmart\",\"name\":\"Walmart\",\"payment_channel\":\"other\",\"payment_meta\":{\"by_order_of\":null,\"payee\":null,\"payer\":null,\"payment_method\":null,\"payment_processor\":null,\"ppd_id\":null,\"reason\":null,\"reference_number\":\"320233330735688096\"},\"pending\":false,\"pending_transaction_id\":null,\"personal_finance_category\":{\"confidence_level\":\"VERY_HIGH\",\"detailed\":\"GENERAL_MERCHANDISE_SUPERSTORES\",\"primary\":\"GENERAL_MERCHANDISE\"},\"personal_finance_category_icon_url\":\"https://plaid-category-icons.plaid.com/PFC_GENERAL_MERCHANDISE.png\",\"transaction_code\":null,\"transaction_id\":\"rmQdnefvAndbfHN5mZ4y703C3vdjk7mozCw1OarL\",\"transaction_type\":\"place\",\"unofficial_currency_code\":null,\"website\":\"walmart.com\"}",
|
|
291
|
+
"plaid_category": "GENERAL_MERCHANDISE_SUPERSTORES",
|
|
292
|
+
"source": "plaid",
|
|
293
|
+
"display_name": "Walmart",
|
|
294
|
+
"display_notes": null,
|
|
295
|
+
"account_display_name": "Amex Plat",
|
|
296
|
+
"tags": [],
|
|
297
|
+
"external_id": null
|
|
298
|
+
}
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
> Example 404 Response
|
|
302
|
+
|
|
303
|
+
```json
|
|
304
|
+
{ "error": "Transaction ID not found." }
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
Returns a single Transaction object
|
|
308
|
+
|
|
309
|
+
### HTTP Request
|
|
310
|
+
|
|
311
|
+
`GET https://api.lunchmoney.dev/v1/transactions/:transaction_id`
|
|
312
|
+
|
|
313
|
+
### Query Parameters
|
|
314
|
+
|
|
315
|
+
| Parameter | Type | Required | Default | Description |
|
|
316
|
+
| ----------------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
317
|
+
| debit_as_negative | boolean | false | false | Pass in true if you’d like expenses to be returned as negative amounts and credits as positive amounts. Defaults to false. |
|
|
318
|
+
|
|
319
|
+
## Insert Transactions
|
|
320
|
+
|
|
321
|
+
Use this endpoint to insert one or more transactions at once. The maximum number of transactions per requests is 500.
|
|
322
|
+
|
|
323
|
+
> Example 200 Response
|
|
324
|
+
>
|
|
325
|
+
> Upon success, IDs of inserted transactions will be returned in an array.
|
|
326
|
+
|
|
327
|
+
```json
|
|
328
|
+
{
|
|
329
|
+
"ids": [54, 55, 56, 57]
|
|
330
|
+
}
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
> Example 404 Response
|
|
334
|
+
>
|
|
335
|
+
> An array of errors will be returned denoting reason why parameters were deemed invalid.
|
|
336
|
+
|
|
337
|
+
```json
|
|
338
|
+
{
|
|
339
|
+
"error": [
|
|
340
|
+
"Transaction 0 is missing date.",
|
|
341
|
+
"Transaction 0 is missing amount.",
|
|
342
|
+
"Transaction 1 status must be either cleared or uncleared: null"
|
|
343
|
+
]
|
|
344
|
+
}
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
### HTTP Request
|
|
348
|
+
|
|
349
|
+
`POST https://api.lunchmoney.dev/v1/transactions`
|
|
350
|
+
|
|
351
|
+
### Body Parameters
|
|
352
|
+
|
|
353
|
+
| Parameter | Type | Required | Default | Description |
|
|
354
|
+
| ------------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
355
|
+
| transactions | array | true | - | List of transactions to insert (see below) |
|
|
356
|
+
| apply_rules | boolean | false | false | If true, will apply account’s existing rules to the inserted transactions. Defaults to false. |
|
|
357
|
+
| skip_duplicates | boolean | false | false | If true, the system will automatically dedupe based on transaction date, payee and amount. Note that deduping by external_id will occur regardless of this flag. |
|
|
358
|
+
| check_for_recurring | boolean | false | false | If true, will check new transactions for occurrences of new monthly expenses. Defaults to false. |
|
|
359
|
+
| debit_as_negative | boolean | false | false | If true, will assume negative amount values denote expenses and positive amount values denote credits. Defaults to false. |
|
|
360
|
+
| skip_balance_update | boolean | false | true | If true, will skip updating balance if an asset_id is present for any of the transactions. |
|
|
361
|
+
|
|
362
|
+
### Transaction Object to Insert
|
|
363
|
+
|
|
364
|
+
| Key | Type | Required | Description |
|
|
365
|
+
|-----------------|---------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
366
|
+
| date | string | true | Must be in ISO 8601 format (YYYY-MM-DD). |
|
|
367
|
+
| amount | number/string | true | Numeric value of amount. i.e. $4.25 should be denoted as 4.25. |
|
|
368
|
+
| category_id | number | false | Unique identifier for associated category_id. Category must be associated with the same account and must not be a category group. |
|
|
369
|
+
| payee | string | false | Max 140 characters |
|
|
370
|
+
| currency | string | false | Three-letter lowercase currency code in ISO 4217 format. The code sent must exist in our database. Defaults to user account's primary currency. |
|
|
371
|
+
| asset_id | number | false | Unique identifier for associated asset (manually-managed account). Asset must be associated with the same account. When set `plaid_account_id` may not be set. |
|
|
372
|
+
| plaid_account_id| number | false | Unique identifier for associated plaid account. This must have the "Allow Modifications to Transactions" option set. When set `asset_id` may not be set. |
|
|
373
|
+
| recurring_id | number | false | Unique identifier for associated recurring expense. Recurring expense must be associated with the same account. |
|
|
374
|
+
| notes | string | false | Max 350 characters |
|
|
375
|
+
| status | string | false | Must be either cleared or uncleared. (Note: special statuses for recurring items have been deprecated.) Defaults to uncleared. |
|
|
376
|
+
| external_id | string | false | User-defined external ID for transaction. Max 75 characters. External IDs must be unique within the same asset_id. |
|
|
377
|
+
| tags | Array of numbers and/or strings | false | Passing in a number will attempt to match by ID. If no matching tag ID is found, an error will be thrown. Passing in a string will attempt to match by string. If no matching tag name is found, a new tag will be created. |
|
|
378
|
+
|
|
379
|
+
## Update Transaction
|
|
380
|
+
|
|
381
|
+
Use this endpoint to update a single transaction. You may also use this to split an existing transaction.
|
|
382
|
+
|
|
383
|
+
> Example 200 Response
|
|
384
|
+
>
|
|
385
|
+
> If a split was part of the request, an array of newly-created split transactions will be returned.
|
|
386
|
+
|
|
387
|
+
```json
|
|
388
|
+
{
|
|
389
|
+
"updated": true,
|
|
390
|
+
"split": [58, 59]
|
|
391
|
+
}
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
> Example 404 Response
|
|
395
|
+
>
|
|
396
|
+
> An array of errors will be returned denoting reason why parameters were deemed invalid.
|
|
397
|
+
|
|
398
|
+
```json
|
|
399
|
+
{ "error": ["This transaction doesn't exist or you don't have access to it."] }
|
|
400
|
+
```
|
|
401
|
+
|
|
402
|
+
```json
|
|
403
|
+
{
|
|
404
|
+
"error": [
|
|
405
|
+
"You cannot change the amount for this transaction because it was automatically imported.",
|
|
406
|
+
"You cannot assign an asset_id for this transaction because it was automatically imported."
|
|
407
|
+
]
|
|
408
|
+
}
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
### HTTP Request
|
|
412
|
+
|
|
413
|
+
`PUT https://api.lunchmoney.dev/v1/transactions/:transaction_id`
|
|
414
|
+
|
|
415
|
+
### Body Parameters
|
|
416
|
+
|
|
417
|
+
| Parameter | Type | Required | Default | Description |
|
|
418
|
+
| ------------------- | ------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
419
|
+
| split | Split[] | see description | - | Defines the split of a transaction. You may not split an already-split transaction, recurring transaction, or group transaction. (see Split object below). If passing an array of split objects to this parameter, the transaction parameter is not required. |
|
|
420
|
+
| transaction | object | see description | - | The transaction update object (see Update Transaction object below). Must include an `id` matching an existing transaction. If passing a transaction object to this parameter, the split parameter is not required. |
|
|
421
|
+
| debit_as_negative | boolean | false | false | If true, will assume negative amount values denote expenses and positive amount values denote credits. Defaults to false. |
|
|
422
|
+
| skip_balance_update | boolean | false | true | If false, will skip updating balance if an asset_id is present for any of the transactions. |
|
|
423
|
+
|
|
424
|
+
### Update Transaction Object
|
|
425
|
+
|
|
426
|
+
| Key | Type | Description |
|
|
427
|
+
| ------------ | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
428
|
+
| date | string | Must be in ISO 8601 format (YYYY-MM-DD). |
|
|
429
|
+
| category_id | number | Unique identifier for associated category_id. Category must belong to the account associated with the API Token used in the request and must not be a category group. |
|
|
430
|
+
| payee | string | Max 140 characters |
|
|
431
|
+
| amount | number or string | You may only update this if this transaction was not created from an automatic import, i.e. if this transaction is not associated with a plaid_account_id |
|
|
432
|
+
| currency | string | You may only update this if this transaction was not created from an automatic import, i.e. if this transaction is not associated with a plaid_account_id. Defaults to user account's primary currency. |
|
|
433
|
+
| asset_id | number | Unique identifier for associated asset (manually-managed account). Asset must belong to the account associated with the API Token used in the request. You may not update this if this transaction currently belongs to a Plaid synced account that does not have the "Allow Modifications to Transactions" property set. This may not be set if plaid_account_id is also set. |
|
|
434
|
+
| plaid_account_id | number | Unique identifier for a synced (Plaid) account. Account must belong to the account associated with the API Token used in the request and have the "Allow Modifications to Transactions" property set. This may not be set if asset_id is also set. |
|
|
435
|
+
| recurring_id | number | Unique identifier for associated recurring expense. Recurring expense must be associated with the same account. |
|
|
436
|
+
| notes | string | Max 350 characters |
|
|
437
|
+
| status | string | Must be either cleared or uncleared. Defaults to uncleared. (Note: special statuses for recurring items have been deprecated.) Defaults to uncleared. |
|
|
438
|
+
| external_id | string | User-defined external ID for transaction. Max 75 characters. External IDs must be unique within the same asset_id. You may only update this if this transaction was not created from an automatic import, i.e. if this transaction is not associated with a plaid_account_id |
|
|
439
|
+
| tags | array of numbers and/or strings | Input must be an array, or error will be thrown. Passing in a number will attempt to match by ID. If no matching tag ID is found, an error will be thrown. Passing in a string will attempt to match by string. If no matching tag name is found, a new tag will be created. Pass in `null` to remove all tags. |
|
|
440
|
+
|
|
441
|
+
### Split Object
|
|
442
|
+
|
|
443
|
+
| Key | Type | Required | Description |
|
|
444
|
+
| ----------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
445
|
+
| payee | string | false | Max 140 characters. Sets to original payee if none defined |
|
|
446
|
+
| date | string | false | Must be in ISO 8601 format (YYYY-MM-DD). Sets to original date if none defined |
|
|
447
|
+
| category_id | number | false | Unique identifier for associated category_id. Category must be associated with the same account. Sets to original category if none defined |
|
|
448
|
+
| notes | string | false | Sets to original notes if none defined |
|
|
449
|
+
| amount | number/string | true | Individual amount of split. Currency will inherit from parent transaction. All amounts must sum up to parent transaction amount. |
|
|
450
|
+
|
|
451
|
+
## Unsplit Transactions
|
|
452
|
+
|
|
453
|
+
Use this endpoint to unsplit one or more transactions.
|
|
454
|
+
|
|
455
|
+
> Example 200 Response
|
|
456
|
+
|
|
457
|
+
```json
|
|
458
|
+
[84389, 23212, 43333]
|
|
459
|
+
```
|
|
460
|
+
|
|
461
|
+
> Example 404 Response
|
|
462
|
+
|
|
463
|
+
```json
|
|
464
|
+
{
|
|
465
|
+
"error": "The following transaction ids are not valid to unsplit: 1232, 1233, 1234"
|
|
466
|
+
}
|
|
467
|
+
```
|
|
468
|
+
|
|
469
|
+
Returns an array of IDs of deleted transactions
|
|
470
|
+
|
|
471
|
+
### HTTP Request
|
|
472
|
+
|
|
473
|
+
`POST https://api.lunchmoney.dev/v1/transactions/unsplit`
|
|
474
|
+
|
|
475
|
+
### Body Parameters
|
|
476
|
+
|
|
477
|
+
| Parameter | Type | Required | Default | Description |
|
|
478
|
+
| -------------- | ---------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------- |
|
|
479
|
+
| parent_ids | array of numbers | true | - | Array of transaction IDs to unsplit. If one transaction is unsplittable, no transaction will be unsplit. |
|
|
480
|
+
| remove_parents | boolean | false | false | If true, deletes the original parent transaction as well. Note, this is not reversible! |
|
|
481
|
+
|
|
482
|
+
## Get Transaction Group
|
|
483
|
+
|
|
484
|
+
Use this endpoint to get the parent transaction and associated children transactions of a transaction group.
|
|
485
|
+
|
|
486
|
+
> Example 200 Response
|
|
487
|
+
|
|
488
|
+
```json
|
|
489
|
+
{
|
|
490
|
+
"id": 481307164,
|
|
491
|
+
"date": "2023-11-29",
|
|
492
|
+
"amount": "0",
|
|
493
|
+
"currency": "usd",
|
|
494
|
+
"to_base": 0,
|
|
495
|
+
"payee": "Walmart+",
|
|
496
|
+
"category_id": 315174,
|
|
497
|
+
"category_name": "General",
|
|
498
|
+
"category_group_id": 315362,
|
|
499
|
+
"category_group_name": "Shopping",
|
|
500
|
+
"is_income": false,
|
|
501
|
+
"exclude_from_budget": false,
|
|
502
|
+
"exclude_from_totals": false,
|
|
503
|
+
"created_at": "2023-11-30T23:59:56.584Z",
|
|
504
|
+
"updated_at": "2023-11-30T23:59:56.584Z",
|
|
505
|
+
"status": "cleared",
|
|
506
|
+
"is_pending": false,
|
|
507
|
+
"notes": null,
|
|
508
|
+
"original_name": null,
|
|
509
|
+
"recurring_id": null,
|
|
510
|
+
"recurring_payee": null,
|
|
511
|
+
"recurring_description": null,
|
|
512
|
+
"recurring_cadence": null,
|
|
513
|
+
"recurring_type": null,
|
|
514
|
+
"recurring_amount": null,
|
|
515
|
+
"recurring_currency": null,
|
|
516
|
+
"parent_id": null,
|
|
517
|
+
"has_children": null,
|
|
518
|
+
"group_id": null,
|
|
519
|
+
"is_group": true,
|
|
520
|
+
"asset_id": null,
|
|
521
|
+
"asset_institution_name": null,
|
|
522
|
+
"asset_name": null,
|
|
523
|
+
"asset_display_name": null,
|
|
524
|
+
"asset_status": null,
|
|
525
|
+
"plaid_account_id": null,
|
|
526
|
+
"plaid_account_name": null,
|
|
527
|
+
"plaid_account_mask": null,
|
|
528
|
+
"institution_name": null,
|
|
529
|
+
"plaid_account_display_name": null,
|
|
530
|
+
"plaid_metadata": null,
|
|
531
|
+
"plaid_category": null,
|
|
532
|
+
"source": null,
|
|
533
|
+
"display_name": "Walmart+",
|
|
534
|
+
"display_notes": null,
|
|
535
|
+
"account_display_name": " ",
|
|
536
|
+
"tags": [],
|
|
537
|
+
"children": [
|
|
538
|
+
{
|
|
539
|
+
"id": 480887173,
|
|
540
|
+
"payee": "Walmart",
|
|
541
|
+
"amount": "-14.1800",
|
|
542
|
+
"currency": "usd",
|
|
543
|
+
"date": "2023-11-29",
|
|
544
|
+
"formatted_date": "2023-11-29",
|
|
545
|
+
"notes": null,
|
|
546
|
+
"asset_id": null,
|
|
547
|
+
"plaid_account_id": 54174,
|
|
548
|
+
"to_base": -14.18
|
|
549
|
+
},
|
|
550
|
+
{
|
|
551
|
+
"id": 480887180,
|
|
552
|
+
"payee": "Walmart",
|
|
553
|
+
"amount": "14.1800",
|
|
554
|
+
"currency": "usd",
|
|
555
|
+
"date": "2023-11-28",
|
|
556
|
+
"formatted_date": "2023-11-28",
|
|
557
|
+
"notes": null,
|
|
558
|
+
"asset_id": null,
|
|
559
|
+
"plaid_account_id": 54174,
|
|
560
|
+
"to_base": 14.18
|
|
561
|
+
}
|
|
562
|
+
],
|
|
563
|
+
"external_id": null
|
|
564
|
+
}
|
|
565
|
+
```
|
|
566
|
+
|
|
567
|
+
> Example 404 Response
|
|
568
|
+
|
|
569
|
+
```json
|
|
570
|
+
{
|
|
571
|
+
"error": [
|
|
572
|
+
"Transaction 35360525 is not a transaction group, or part of a transaction group."
|
|
573
|
+
]
|
|
574
|
+
}
|
|
575
|
+
```
|
|
576
|
+
|
|
577
|
+
Returns the hydrated parent transaction of a transaction group
|
|
578
|
+
|
|
579
|
+
### HTTP Request
|
|
580
|
+
|
|
581
|
+
`GET https://api.lunchmoney.dev/v1/transactions/group`
|
|
582
|
+
|
|
583
|
+
### Query Parameters
|
|
584
|
+
|
|
585
|
+
| Parameter | Type | Required | Description |
|
|
586
|
+
| -------------- | ------ | -------- | ----------------------------------------------------------------------------------- |
|
|
587
|
+
| transaction_id | number | true | Transaction ID of either the parent or any of the children in the transaction group |
|
|
588
|
+
|
|
589
|
+
## Create Transaction Group
|
|
590
|
+
|
|
591
|
+
Use this endpoint to create a transaction group of two or more transactions.
|
|
592
|
+
|
|
593
|
+
> Example 200 Response
|
|
594
|
+
|
|
595
|
+
```json
|
|
596
|
+
84389
|
|
597
|
+
```
|
|
598
|
+
|
|
599
|
+
> Example 404 Response
|
|
600
|
+
|
|
601
|
+
```json
|
|
602
|
+
{
|
|
603
|
+
"error": [
|
|
604
|
+
"Transaction 35360525 is in a transaction group already (35717487) and cannot be added to another transaction group."
|
|
605
|
+
]
|
|
606
|
+
}
|
|
607
|
+
```
|
|
608
|
+
|
|
609
|
+
Returns the ID of the newly created transaction group
|
|
610
|
+
|
|
611
|
+
### HTTP Request
|
|
612
|
+
|
|
613
|
+
`POST https://api.lunchmoney.dev/v1/transactions/group`
|
|
614
|
+
|
|
615
|
+
### Body Parameters
|
|
616
|
+
|
|
617
|
+
| Parameter | Type | Required | Default | Description |
|
|
618
|
+
| ------------ | ------ | -------- | ------- | ------------------------------------------------------------ |
|
|
619
|
+
| date | string | true | - | Date for the grouped transaction |
|
|
620
|
+
| payee | string | true | - | Payee name for the grouped transaction |
|
|
621
|
+
| category_id | number | false | - | Category for the grouped transaction |
|
|
622
|
+
| notes | string | false | - | Notes for the grouped transaction |
|
|
623
|
+
| tags | array | false | - | Array of tag IDs for the grouped transaction |
|
|
624
|
+
| transactions | array | true | - | Array of transaction IDs to be part of the transaction group |
|
|
625
|
+
|
|
626
|
+
## Delete Transaction Group
|
|
627
|
+
|
|
628
|
+
Use this endpoint to delete a transaction group. The transactions within the group will not be removed.
|
|
629
|
+
|
|
630
|
+
> Example 200 Response
|
|
631
|
+
|
|
632
|
+
```json
|
|
633
|
+
{ "transactions": [121232, 324324, 545455] }
|
|
634
|
+
```
|
|
635
|
+
|
|
636
|
+
> Example 404 Response
|
|
637
|
+
|
|
638
|
+
```json
|
|
639
|
+
{ "error": ["No transactions found for this group_id 35717487."] }
|
|
640
|
+
```
|
|
641
|
+
|
|
642
|
+
Returns the IDs of the transactions that were part of the deleted group
|
|
643
|
+
|
|
644
|
+
### HTTP Request
|
|
645
|
+
|
|
646
|
+
`DELETE https://api.lunchmoney.dev/v1/transactions/group/:transaction_id`
|
|
647
|
+
|
|
648
|
+
---
|