Sign inBook a demo
HomeGuidesAPI ReferenceGlossary
HomeGuidesAPI ReferenceGlossary
  • API Reference
Logo
Sign inBook a demo
API ReferenceInvoice

Search invoices

GET
https://api.mercoa.com/invoices
GET
/invoices
1curl -G https://api.mercoa.com/invoices \
2     -H "Authorization: Bearer <token>" \
3     -d entityId=ent_8545a84e-a45f-41bf-bdf1-33b42a55812c
Try it
200Find invoices created by a specific entity
1{
2  "count": 10,
3  "hasMore": true,
4  "data": [
5    {
6      "approvalPolicy": [
7        {
8          "id": "apvl_8545a84e-a45f-41bf-bdf1-33b42a55812c",
9          "trigger": [
10            {
11              "type": "amount",
12              "amount": 100,
13              "currency": "USD"
14            }
15          ],
16          "rule": {
17            "type": "approver",
18            "identifierList": {
19              "type": "rolesList",
20              "value": [
21                "Admin",
22                "Controller"
23              ]
24            },
25            "numApprovers": 2
26          },
27          "upstreamPolicyId": "root",
28          "createdAt": "2024-01-01T00:00:00Z",
29          "updatedAt": "2024-01-02T00:00:00Z"
30        }
31      ],
32      "approvers": [
33        {
34          "approvalPolicyId": "apvl_5ce50275-1789-42ea-bc60-bb7e6d03635c",
35          "approvalSlotId": "inap_9bb311c9-7c15-4c9e-8148-63814e0abec6",
36          "action": "APPROVE",
37          "eligibleRoles": [
38            "admin"
39          ],
40          "eligibleUserIds": [
41            "user_e24fc81c-c5ee-47e8-af42-4fe29d895506"
42          ],
43          "date": "2021-01-01T00:00:00Z",
44          "assignedUserId": "user_e24fc81c-c5ee-47e8-af42-4fe29d895506"
45        }
46      ],
47      "createdAt": "2021-01-01T00:00:00Z",
48      "hasDocuments": true,
49      "hasSourceEmail": true,
50      "id": "in_26e7b5d3-a739-4b23-9ad9-6aaa085f47a9",
51      "metadata": {
52        "key1": "value1",
53        "key2": "value2"
54      },
55      "paymentDestinationConfirmed": true,
56      "status": "PAID",
57      "updatedAt": "2021-01-01T00:00:00Z",
58      "amount": 100,
59      "comments": [
60        {
61          "id": "ic_b3525b66-da94-4525-9f31-426bcf657128",
62          "text": "This is an approval comment",
63          "createdAt": "2021-01-01T00:00:00Z",
64          "updatedAt": "2021-01-01T00:00:00Z",
65          "user": {
66            "id": "user_ec3aafc8-ea86-408a-a6c1-545497badbbb",
67            "roles": [
68              "admin",
69              "approver"
70            ],
71            "createdAt": "2024-01-01T00:00:00Z",
72            "updatedAt": "2024-01-01T00:00:00Z",
73            "foreignId": "MY-DB-ID-12345",
74            "email": "john.doe@acme.com",
75            "name": "John Doe"
76          },
77          "associatedApprovalAction": {
78            "userId": "user_e24fc81c-c5ee-47e8-af42-4fe29d895506",
79            "action": "APPROVE"
80          }
81        }
82      ],
83      "creatorUser": {
84        "id": "user_ec3aafc8-ea86-408a-a6c1-545497badbbb",
85        "roles": [
86          "admin",
87          "approver"
88        ],
89        "createdAt": "2024-01-01T00:00:00Z",
90        "updatedAt": "2024-01-01T00:00:00Z",
91        "foreignId": "MY-DB-ID-12345",
92        "email": "john.doe@acme.com",
93        "name": "John Doe"
94      },
95      "currency": "USD",
96      "deductionDate": "2021-01-01T00:00:00Z",
97      "dueDate": "2021-01-31T00:00:00Z",
98      "foreignId": "YOUR-DATABASE-ID",
99      "invoiceDate": "2021-01-01T00:00:00Z",
100      "invoiceNumber": "INV-123",
101      "lineItems": [
102        {
103          "id": "inli_26672f38-eb9a-48f1-a7a0-f1b855e38cd7",
104          "currency": "USD",
105          "category": "EXPENSE",
106          "createdAt": "2021-01-01T00:00:00Z",
107          "updatedAt": "2021-01-01T00:00:00Z",
108          "amount": 100,
109          "description": "Product A",
110          "name": "Product A",
111          "quantity": 1,
112          "unitPrice": 100,
113          "serviceStartDate": "2021-01-01T00:00:00Z",
114          "serviceEndDate": "2021-01-31T00:00:00Z",
115          "metadata": {
116            "key1": "value1",
117            "key2": "value2"
118          },
119          "glAccountId": "600394"
120        }
121      ],
122      "noteToSelf": "For the month of January",
123      "payer": {
124        "acceptedTos": true,
125        "accountType": "business",
126        "createdAt": "2024-01-01T00:00:00Z",
127        "email": "customer@acme.com",
128        "id": "ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
129        "isCustomer": true,
130        "isNetworkPayee": false,
131        "isNetworkPayor": false,
132        "isPayee": false,
133        "isPayor": true,
134        "name": "Acme Inc.",
135        "profile": {
136          "business": {
137            "legalBusinessName": "Acme Inc.",
138            "taxIDProvided": true,
139            "email": "customer@acme.com",
140            "businessType": "llc",
141            "phone": {
142              "countryCode": "1",
143              "number": "4155551234"
144            },
145            "address": {
146              "addressLine1": "123 Main St",
147              "city": "San Francisco",
148              "stateOrProvince": "CA",
149              "postalCode": "94105",
150              "addressLine2": "Unit 1",
151              "country": "US"
152            },
153            "ownersProvided": true,
154            "taxId": {
155              "ein": {
156                "number": "12-3456789"
157              }
158            }
159          }
160        },
161        "status": "verified",
162        "updatedAt": "2024-01-02T00:00:00Z",
163        "accounts": [
164          {
165            "accountId": "85866843",
166            "postalCode": "94105",
167            "nameOnAccount": "John Doe"
168          }
169        ],
170        "counterpartyType": [
171          "ENTITY"
172        ],
173        "foreignId": "MY-DB-ID-12345",
174        "paymentMethods": [
175          {
176            "type": "bankAccount",
177            "accountName": "My Checking Account",
178            "accountNumber": "99988767623",
179            "accountType": "CHECKING",
180            "bankName": "Chase",
181            "createdAt": "2021-01-01T00:00:00Z",
182            "frozen": false,
183            "id": "pm_4794d597-70dc-4fec-b6ec-c5988e759769",
184            "isDefaultDestination": true,
185            "isDefaultSource": true,
186            "metadata": {},
187            "routingNumber": "12345678",
188            "status": "VERIFIED",
189            "supportedCurrencies": [
190              "USD"
191            ],
192            "updatedAt": "2021-01-01T00:00:00Z",
193            "confirmedByEntity": true
194          }
195        ]
196      },
197      "payerId": "ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
198      "paymentDestination": {
199        "type": "check",
200        "addressLine1": "123 Main St",
201        "city": "New York",
202        "country": "US",
203        "createdAt": "2021-01-01T00:00:00Z",
204        "frozen": false,
205        "id": "pm_5fde2f4a-facc-48ef-8f0d-6b7d087c7b18",
206        "isDefaultDestination": true,
207        "isDefaultSource": false,
208        "metadata": {},
209        "payToTheOrderOf": "John Doe",
210        "postalCode": "10001",
211        "stateOrProvince": "NY",
212        "supportedCurrencies": [
213          "USD"
214        ],
215        "updatedAt": "2021-01-01T00:00:00Z",
216        "addressLine2": "Apt 1",
217        "confirmedByEntity": true
218      },
219      "paymentDestinationId": "pm_5fde2f4a-facc-48ef-8f0d-6b7d087c7b18",
220      "paymentDestinationOptions": {
221        "type": "check",
222        "delivery": "MAIL",
223        "printDescription": true
224      },
225      "paymentSource": {
226        "type": "bankAccount",
227        "accountName": "My Checking Account",
228        "accountNumber": "99988767623",
229        "accountType": "CHECKING",
230        "bankName": "Chase",
231        "createdAt": "2021-01-01T00:00:00Z",
232        "frozen": false,
233        "id": "pm_4794d597-70dc-4fec-b6ec-c5988e759769",
234        "isDefaultDestination": true,
235        "isDefaultSource": true,
236        "metadata": {},
237        "routingNumber": "12345678",
238        "status": "VERIFIED",
239        "supportedCurrencies": [
240          "USD"
241        ],
242        "updatedAt": "2021-01-01T00:00:00Z",
243        "confirmedByEntity": true
244      },
245      "paymentSourceId": "pm_4794d597-70dc-4fec-b6ec-c5988e759769",
246      "paymentSourceOptions": {
247        "type": "bnpl",
248        "acceptedTerms": true,
249        "defermentWeeks": 8,
250        "installmentsStartDate": "2025-06-18"
251      },
252      "processedAt": "2021-01-01T00:00:00Z",
253      "serviceEndDate": "2021-01-31T00:00:00Z",
254      "serviceStartDate": "2021-01-01T00:00:00Z",
255      "settlementDate": "2021-01-03T00:00:00Z",
256      "transactions": [
257        {
258          "type": "bankAccountToBankAccount",
259          "amount": 10000,
260          "createdAt": "2024-01-01T00:00:00Z",
261          "currency": "USD",
262          "id": "trx_bb08e72f-19f8-45f3-bcf9-46fdc46cb2f4",
263          "payer": {
264            "acceptedTos": true,
265            "accountType": "business",
266            "createdAt": "2024-01-01T00:00:00Z",
267            "email": "customer@acme.com",
268            "id": "ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
269            "isCustomer": true,
270            "isNetworkPayee": false,
271            "isNetworkPayor": false,
272            "isPayee": false,
273            "isPayor": true,
274            "name": "Acme Inc.",
275            "profile": {
276              "business": {
277                "legalBusinessName": "Acme Inc.",
278                "taxIDProvided": true,
279                "email": "customer@acme.com",
280                "businessType": "llc",
281                "phone": {
282                  "countryCode": "1",
283                  "number": "4155551234"
284                },
285                "address": {
286                  "addressLine1": "123 Main St",
287                  "city": "San Francisco",
288                  "stateOrProvince": "CA",
289                  "postalCode": "94105",
290                  "addressLine2": "Unit 1",
291                  "country": "US"
292                },
293                "ownersProvided": true,
294                "taxId": {
295                  "ein": {
296                    "number": "12-3456789"
297                  }
298                }
299              }
300            },
301            "status": "verified",
302            "updatedAt": "2024-01-02T00:00:00Z",
303            "accounts": [
304              {
305                "accountId": "85866843",
306                "postalCode": "94105",
307                "nameOnAccount": "John Doe"
308              }
309            ],
310            "counterpartyType": [
311              "ENTITY"
312            ],
313            "foreignId": "MY-DB-ID-12345",
314            "paymentMethods": [
315              {
316                "type": "bankAccount",
317                "accountName": "My Checking Account",
318                "accountNumber": "99988767623",
319                "accountType": "CHECKING",
320                "bankName": "Chase",
321                "createdAt": "2021-01-01T00:00:00Z",
322                "frozen": false,
323                "id": "pm_4794d597-70dc-4fec-b6ec-c5988e759769",
324                "isDefaultDestination": true,
325                "isDefaultSource": true,
326                "metadata": {},
327                "routingNumber": "12345678",
328                "status": "VERIFIED",
329                "supportedCurrencies": [
330                  "USD"
331                ],
332                "updatedAt": "2021-01-01T00:00:00Z",
333                "confirmedByEntity": true
334              }
335            ]
336          },
337          "payerId": "ent_bb08e72f-19f8-45f3-bcf9-46fdc46cb2f4",
338          "paymentDestination": {
339            "type": "bankAccount",
340            "accountName": "My Checking Account",
341            "accountNumber": "99988767623",
342            "accountType": "CHECKING",
343            "bankName": "Chase",
344            "createdAt": "2021-01-01T00:00:00Z",
345            "frozen": false,
346            "id": "pm_4794d597-70dc-4fec-b6ec-c5988e759769",
347            "isDefaultDestination": true,
348            "isDefaultSource": true,
349            "metadata": {},
350            "routingNumber": "12345678",
351            "status": "VERIFIED",
352            "supportedCurrencies": [
353              "USD"
354            ],
355            "updatedAt": "2021-01-01T00:00:00Z",
356            "confirmedByEntity": true
357          },
358          "paymentDestinationId": "pm_65523ab0-043d-4706-b2b2-0b73fed92269",
359          "paymentSource": {
360            "type": "bankAccount",
361            "accountName": "My Checking Account",
362            "accountNumber": "99988767623",
363            "accountType": "CHECKING",
364            "bankName": "Chase",
365            "createdAt": "2021-01-01T00:00:00Z",
366            "frozen": false,
367            "id": "pm_4794d597-70dc-4fec-b6ec-c5988e759769",
368            "isDefaultDestination": true,
369            "isDefaultSource": true,
370            "metadata": {},
371            "routingNumber": "12345678",
372            "status": "VERIFIED",
373            "supportedCurrencies": [
374              "USD"
375            ],
376            "updatedAt": "2021-01-01T00:00:00Z",
377            "confirmedByEntity": true
378          },
379          "paymentSourceId": "pm_65523ab0-043d-4706-b2b2-0b73fed92269",
380          "status": "COMPLETED",
381          "updatedAt": "2024-01-01T00:00:00Z",
382          "vendor": {
383            "acceptedTos": false,
384            "accountType": "business",
385            "createdAt": "2024-01-01T00:00:00Z",
386            "email": "vendor@bigboxstore.com",
387            "id": "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d",
388            "isCustomer": false,
389            "isNetworkPayee": false,
390            "isNetworkPayor": false,
391            "isPayee": true,
392            "isPayor": false,
393            "name": "Big Box Store",
394            "profile": {
395              "business": {
396                "legalBusinessName": "Big Box Store",
397                "taxIDProvided": false,
398                "email": "vendor@bigboxstore.com",
399                "businessType": "publicCorporation",
400                "ownersProvided": false
401              }
402            },
403            "status": "unverified",
404            "updatedAt": "2024-01-02T00:00:00Z",
405            "counterpartyType": [
406              "ENTITY"
407            ],
408            "foreignId": "MY-DB-ID-90909",
409            "paymentMethods": [
410              {
411                "type": "bankAccount",
412                "accountName": "Vendor Checking Account",
413                "accountNumber": "55934059697648",
414                "accountType": "CHECKING",
415                "bankName": "Chase",
416                "createdAt": "2021-01-01T00:00:00Z",
417                "frozen": false,
418                "id": "pm_7610541f-4619-4033-8620-cfccfb811293",
419                "isDefaultDestination": true,
420                "isDefaultSource": true,
421                "metadata": {},
422                "routingNumber": "66554433",
423                "status": "NEW",
424                "supportedCurrencies": [
425                  "USD"
426                ],
427                "updatedAt": "2021-01-01T00:00:00Z",
428                "confirmedByEntity": false
429              }
430            ]
431          },
432          "vendorId": "ent_bb08e72f-19f8-45f3-bcf9-46fdc46cb2f4"
433        }
434      ],
435      "vendor": {
436        "acceptedTos": false,
437        "accountType": "business",
438        "createdAt": "2024-01-01T00:00:00Z",
439        "email": "vendor@bigboxstore.com",
440        "id": "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d",
441        "isCustomer": false,
442        "isNetworkPayee": false,
443        "isNetworkPayor": false,
444        "isPayee": true,
445        "isPayor": false,
446        "name": "Big Box Store",
447        "profile": {
448          "business": {
449            "legalBusinessName": "Big Box Store",
450            "taxIDProvided": false,
451            "email": "vendor@bigboxstore.com",
452            "businessType": "publicCorporation",
453            "ownersProvided": false
454          }
455        },
456        "status": "unverified",
457        "updatedAt": "2024-01-02T00:00:00Z",
458        "counterpartyType": [
459          "ENTITY"
460        ],
461        "foreignId": "MY-DB-ID-90909",
462        "paymentMethods": [
463          {
464            "type": "bankAccount",
465            "accountName": "Vendor Checking Account",
466            "accountNumber": "55934059697648",
467            "accountType": "CHECKING",
468            "bankName": "Chase",
469            "createdAt": "2021-01-01T00:00:00Z",
470            "frozen": false,
471            "id": "pm_7610541f-4619-4033-8620-cfccfb811293",
472            "isDefaultDestination": true,
473            "isDefaultSource": true,
474            "metadata": {},
475            "routingNumber": "66554433",
476            "status": "NEW",
477            "supportedCurrencies": [
478              "USD"
479            ],
480            "updatedAt": "2021-01-01T00:00:00Z",
481            "confirmedByEntity": false
482          }
483        ]
484      },
485      "vendorId": "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d"
486    }
487  ]
488}
Search invoices for all entities in the organization
Was this page helpful?
Previous

Create

Next
Built with
Create
Search invoices for all entities in the organization

Authentication

AuthorizationBearer
Bearer authentication of the form `Bearer <token>`, where token is your auth token.

Query parameters

entityIdstringOptional
Filter invoices by the ID or foreign ID of the entity that is the payer or the vendor of the invoice.
entityGroupIdstringOptional
Filter invoices by the ID or foreign ID of the entity group that the entity belongs to.
startDatedatetimeOptional
Start date filter. Defaults to CREATED_AT unless specified the dateType is specified
endDatedatetimeOptional
End date filter. Defaults to CREATED_AT unless specified the dateType is specified
dateTypeenumOptional
Type of date to filter by if startDate and endDate filters are provided. Defaults to CREATED_AT.
orderByenumOptional
Field to order invoices by. Defaults to CREATED_AT.
orderDirectionenumOptional
Direction to order invoices by. Defaults to asc.
Allowed values:
limitintegerOptional
Number of invoices to return. Limit can range between 1 and 100, and the default is 10.
startingAfterstringOptional
The ID of the invoice to start after. If not provided, the first page of invoices will be returned.
searchstringOptional
Find invoices by vendor name, invoice number, check number, or amount. Partial matches are supported.
metadataobjectOptional
Filter invoices by metadata. Each filter will be applied as an AND condition. Duplicate keys will be ignored.
lineItemMetadataobjectOptional
Filter invoices by line item metadata. Each filter will be applied as an AND condition. Duplicate keys will be ignored.
lineItemGlAccountIdstringOptional
Filter invoices by line item GL account ID. Each filter will be applied as an OR condition. Duplicate keys will be ignored.
payerIdstringOptional
Filter invoices by payer ID or payer foreign ID.
vendorIdstringOptional
Filter invoices by vendor ID or vendor foreign ID.
creatorUserIdstringOptional
Filter invoices by the ID or foreign ID of the user that created the invoice.
approverIdstringOptional
Filter invoices by assigned approver user ID. Only invoices with all upstream policies approved will be returned.
approverActionenumOptional
Filter invoices by approver action. Needs to be used with approverId. For example, if you want to find all invoices that have been approved by a specific user, you would use approverId and approverAction=APPROVE.
Allowed values:
approverCountstringOptional
Filter invoices by the number of approvers. Use exact number (e.g., 3) or range (e.g., ">3", "<5", ">=2", "<=4").
invoiceIdstringOptional
Filter invoices by invoice ID or invoice foreign ID.
statusenumOptional
Invoice status to filter on
paymentTypelist of enumsOptional
Filter invoices by recurring status
Allowed values:
invoiceTemplateIdstringOptional
Filter invoice by invoice template ID
returnPayerMetadatabooleanOptional
Whether to return payer metadata in the response
returnVendorMetadatabooleanOptional
Whether to return vendor metadata in the response
returnPaymentTimingbooleanOptional
Whether to return payment timing in the response

Response

This endpoint returns an object.
countinteger
Total number of notifications for the given start and end date filters. This value is not limited by the limit parameter. It is provided so that you can determine how many pages of results are available.
hasMoreboolean
True if there are more notifications available for the given start and end date filters.
datalist of objects

Errors

Direction to order invoices by. Defaults to asc.
Number of invoices to return. Limit can range between 1 and 100, and the default is 10.
The ID of the invoice to start after. If not provided, the first page of invoices will be returned.
Find invoices by vendor name, invoice number, check number, or amount. Partial matches are supported.
Filter invoices by metadata. Each filter will be applied as an AND condition. Duplicate keys will be ignored.
Filter invoices by line item metadata. Each filter will be applied as an AND condition. Duplicate keys will be ignored.
Filter invoices by line item GL account ID. Each filter will be applied as an OR condition. Duplicate keys will be ignored.
Filter invoices by payer ID or payer foreign ID.
Filter invoices by vendor ID or vendor foreign ID.
Filter invoices by the ID or foreign ID of the user that created the invoice.
Filter invoices by assigned approver user ID. Only invoices with all upstream policies approved will be returned.
Filter invoices by invoice ID or invoice foreign ID.
Invoice status to filter on
Filter invoices by recurring status
Filter invoice by invoice template ID
Whether to return payer metadata in the response
Whether to return vendor metadata in the response
Whether to return payment timing in the response

Bearer authentication of the form Bearer <token>, where token is your auth token.

Filter invoices by approver action. Needs to be used with approverId. For example, if you want to find all invoices that have been approved by a specific user, you would use approverId and approverAction=APPROVE.

Field to order invoices by. Defaults to CREATED_AT.

Start date filter. Defaults to CREATED_AT unless specified the dateType is specified

Type of date to filter by if startDate and endDate filters are provided. Defaults to CREATED_AT.

End date filter. Defaults to CREATED_AT unless specified the dateType is specified