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

Create

POST
https://api.mercoa.com/invoice-template
POST
/invoice-template
1curl -X POST https://api.mercoa.com/invoice-template \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "amount": 100,
6  "creatorEntityId": "ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
7  "creatorUserId": "user_e24fc81c-c5ee-47e8-af42-4fe29d895506",
8  "currency": "USD",
9  "deductionDate": "2021-01-10T00:00:00Z",
10  "dueDate": "2021-01-13T00:00:00Z",
11  "invoiceDate": "2021-01-01T00:00:00Z",
12  "invoiceNumber": "INV-123",
13  "lineItems": [
14    {
15      "amount": 100,
16      "category": "EXPENSE",
17      "currency": "USD",
18      "description": "Product A",
19      "glAccountId": "600394",
20      "metadata": {
21        "key1": "value1",
22        "key2": "value2"
23      },
24      "name": "Product A",
25      "quantity": 1,
26      "serviceEndDate": "2021-01-31T00:00:00Z",
27      "serviceStartDate": "2021-01-01T00:00:00Z",
28      "unitPrice": 100
29    }
30  ],
31  "noteToSelf": "Monthly recurring payment",
32  "payerId": "ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
33  "paymentDestinationId": "pm_5fde2f4a-facc-48ef-8f0d-6b7d087c7b18",
34  "paymentDestinationOptions": {
35    "type": "check",
36    "delivery": "MAIL",
37    "printDescription": true
38  },
39  "paymentSchedule": {
40    "type": "monthly",
41    "repeatOnDay": 10,
42    "ends": "2021-01-01T00:00:00Z"
43  },
44  "paymentSourceId": "pm_4794d597-70dc-4fec-b6ec-c5988e759769",
45  "status": "NEW",
46  "vendorId": "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d"
47}'
Try it
200Create an invoice template
1{
2  "approvalPolicy": [
3    {
4      "id": "apvl_8545a84e-a45f-41bf-bdf1-33b42a55812c",
5      "trigger": [
6        {
7          "type": "amount",
8          "amount": 100,
9          "currency": "USD"
10        }
11      ],
12      "rule": {
13        "type": "approver",
14        "identifierList": {
15          "type": "rolesList",
16          "value": [
17            "Admin",
18            "Controller"
19          ]
20        },
21        "numApprovers": 2
22      },
23      "upstreamPolicyId": "root",
24      "createdAt": "2024-01-01T00:00:00Z",
25      "updatedAt": "2024-01-02T00:00:00Z"
26    }
27  ],
28  "approvers": [
29    {
30      "approvalPolicyId": "apvl_5ce50275-1789-42ea-bc60-bb7e6d03635c",
31      "approvalSlotId": "inap_9bb311c9-7c15-4c9e-8148-63814e0abec6",
32      "action": "APPROVE",
33      "eligibleRoles": [
34        "admin"
35      ],
36      "eligibleUserIds": [
37        "user_e24fc81c-c5ee-47e8-af42-4fe29d895506"
38      ],
39      "date": "2021-01-01T00:00:00Z",
40      "assignedUserId": "user_e24fc81c-c5ee-47e8-af42-4fe29d895506"
41    }
42  ],
43  "createdAt": "2021-01-01T00:00:00Z",
44  "hasDocuments": true,
45  "hasSourceEmail": true,
46  "id": "invt_13c07096-5848-4aeb-ae7d-6576289034c4",
47  "metadata": {
48    "key1": "value1",
49    "key2": "value2"
50  },
51  "paymentDestinationConfirmed": true,
52  "status": "SCHEDULED",
53  "updatedAt": "2021-01-01T00:00:00Z",
54  "amount": 100,
55  "creatorUser": {
56    "id": "user_ec3aafc8-ea86-408a-a6c1-545497badbbb",
57    "roles": [
58      "admin",
59      "approver"
60    ],
61    "createdAt": "2024-01-01T00:00:00Z",
62    "updatedAt": "2024-01-01T00:00:00Z",
63    "foreignId": "MY-DB-ID-12345",
64    "email": "john.doe@acme.com",
65    "name": "John Doe"
66  },
67  "currency": "USD",
68  "deductionDate": "2021-01-01T00:00:00Z",
69  "invoiceDate": "2021-01-01T00:00:00Z",
70  "invoiceNumber": "INV-123",
71  "lineItems": [
72    {
73      "id": "inli_26672f38-eb9a-48f1-a7a0-f1b855e38cd7",
74      "currency": "USD",
75      "category": "EXPENSE",
76      "createdAt": "2021-01-01T00:00:00Z",
77      "updatedAt": "2021-01-01T00:00:00Z",
78      "amount": 100,
79      "description": "Product A",
80      "name": "Product A",
81      "quantity": 1,
82      "unitPrice": 100,
83      "serviceStartDate": "2021-01-01T00:00:00Z",
84      "serviceEndDate": "2021-01-31T00:00:00Z",
85      "metadata": {
86        "key1": "value1",
87        "key2": "value2"
88      },
89      "glAccountId": "600394"
90    }
91  ],
92  "noteToSelf": "For the month of January",
93  "payer": {
94    "acceptedTos": true,
95    "accountType": "business",
96    "createdAt": "2024-01-01T00:00:00Z",
97    "email": "customer@acme.com",
98    "id": "ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
99    "isCustomer": true,
100    "isNetworkPayee": false,
101    "isNetworkPayor": false,
102    "isPayee": false,
103    "isPayor": true,
104    "name": "Acme Inc.",
105    "profile": {
106      "business": {
107        "legalBusinessName": "Acme Inc.",
108        "taxIDProvided": true,
109        "email": "customer@acme.com",
110        "businessType": "llc",
111        "phone": {
112          "countryCode": "1",
113          "number": "4155551234"
114        },
115        "address": {
116          "addressLine1": "123 Main St",
117          "city": "San Francisco",
118          "stateOrProvince": "CA",
119          "postalCode": "94105",
120          "addressLine2": "Unit 1",
121          "country": "US"
122        },
123        "ownersProvided": true,
124        "taxId": {
125          "ein": {
126            "number": "12-3456789"
127          }
128        }
129      }
130    },
131    "status": "verified",
132    "updatedAt": "2024-01-02T00:00:00Z",
133    "accounts": [
134      {
135        "accountId": "85866843",
136        "postalCode": "94105",
137        "nameOnAccount": "John Doe"
138      }
139    ],
140    "counterpartyType": [
141      "ENTITY"
142    ],
143    "foreignId": "MY-DB-ID-12345",
144    "paymentMethods": [
145      {
146        "type": "bankAccount",
147        "accountName": "My Checking Account",
148        "accountNumber": "99988767623",
149        "accountType": "CHECKING",
150        "bankName": "Chase",
151        "createdAt": "2021-01-01T00:00:00Z",
152        "frozen": false,
153        "id": "pm_4794d597-70dc-4fec-b6ec-c5988e759769",
154        "isDefaultDestination": true,
155        "isDefaultSource": true,
156        "metadata": {},
157        "routingNumber": "12345678",
158        "status": "VERIFIED",
159        "supportedCurrencies": [
160          "USD"
161        ],
162        "updatedAt": "2021-01-01T00:00:00Z",
163        "confirmedByEntity": true
164      }
165    ]
166  },
167  "payerId": "ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
168  "paymentDestination": {
169    "type": "check",
170    "addressLine1": "123 Main St",
171    "city": "New York",
172    "country": "US",
173    "createdAt": "2021-01-01T00:00:00Z",
174    "frozen": false,
175    "id": "pm_5fde2f4a-facc-48ef-8f0d-6b7d087c7b18",
176    "isDefaultDestination": true,
177    "isDefaultSource": false,
178    "metadata": {},
179    "payToTheOrderOf": "John Doe",
180    "postalCode": "10001",
181    "stateOrProvince": "NY",
182    "supportedCurrencies": [
183      "USD"
184    ],
185    "updatedAt": "2021-01-01T00:00:00Z",
186    "addressLine2": "Apt 1",
187    "confirmedByEntity": true
188  },
189  "paymentDestinationId": "pm_5fde2f4a-facc-48ef-8f0d-6b7d087c7b18",
190  "paymentDestinationOptions": {
191    "type": "check",
192    "delivery": "MAIL",
193    "printDescription": true
194  },
195  "paymentSource": {
196    "type": "bankAccount",
197    "accountName": "My Checking Account",
198    "accountNumber": "99988767623",
199    "accountType": "CHECKING",
200    "bankName": "Chase",
201    "createdAt": "2021-01-01T00:00:00Z",
202    "frozen": false,
203    "id": "pm_4794d597-70dc-4fec-b6ec-c5988e759769",
204    "isDefaultDestination": true,
205    "isDefaultSource": true,
206    "metadata": {},
207    "routingNumber": "12345678",
208    "status": "VERIFIED",
209    "supportedCurrencies": [
210      "USD"
211    ],
212    "updatedAt": "2021-01-01T00:00:00Z",
213    "confirmedByEntity": true
214  },
215  "paymentSourceId": "pm_4794d597-70dc-4fec-b6ec-c5988e759769",
216  "serviceEndDate": "2021-01-31T00:00:00Z",
217  "serviceStartDate": "2021-01-01T00:00:00Z",
218  "vendor": {
219    "acceptedTos": false,
220    "accountType": "business",
221    "createdAt": "2024-01-01T00:00:00Z",
222    "email": "vendor@bigboxstore.com",
223    "id": "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d",
224    "isCustomer": false,
225    "isNetworkPayee": false,
226    "isNetworkPayor": false,
227    "isPayee": true,
228    "isPayor": false,
229    "name": "Big Box Store",
230    "profile": {
231      "business": {
232        "legalBusinessName": "Big Box Store",
233        "taxIDProvided": false,
234        "email": "vendor@bigboxstore.com",
235        "businessType": "publicCorporation",
236        "ownersProvided": false
237      }
238    },
239    "status": "unverified",
240    "updatedAt": "2024-01-02T00:00:00Z",
241    "counterpartyType": [
242      "ENTITY"
243    ],
244    "foreignId": "MY-DB-ID-90909",
245    "paymentMethods": [
246      {
247        "type": "bankAccount",
248        "accountName": "Vendor Checking Account",
249        "accountNumber": "55934059697648",
250        "accountType": "CHECKING",
251        "bankName": "Chase",
252        "createdAt": "2021-01-01T00:00:00Z",
253        "frozen": false,
254        "id": "pm_7610541f-4619-4033-8620-cfccfb811293",
255        "isDefaultDestination": true,
256        "isDefaultSource": true,
257        "metadata": {},
258        "routingNumber": "66554433",
259        "status": "NEW",
260        "supportedCurrencies": [
261          "USD"
262        ],
263        "updatedAt": "2021-01-01T00:00:00Z",
264        "confirmedByEntity": false
265      }
266    ]
267  },
268  "vendorId": "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d"
269}
Was this page helpful?
Previous

Get

Next
Built with
Get

Authentication

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

Request

This endpoint expects an object.
amountdoubleOptional
Total amount of invoice in major units. If the entered amount has more decimal places than the currency supports, trailing decimals will be truncated.
approverslist of objectsOptional
Set approvers for this invoice.
batchPaymentbooleanOptional
If true, this invoice will be paid as a batch payment. Batches are automatically determined by Mercoa based on the payment source, destination, and scheduled payment date.
creatorEntityIdstringOptional
ID of the entity who created this invoice template.
creatorUserIdstringOptional
User ID or Foreign ID of entity user who created this invoice.
currencyenumOptional
Currency code for the amount. Defaults to USD.
deductionDatedatetimeOptional
Initial date when funds are scheduled to be deducted from payer's account.
documentstringOptional
Base64-encoded string. Supported file types include PNG, JPG, WEBP, PDF, and all Microsoft Office formats (automatically converted to PDF). Max file size 10MB.
dueDatedatetimeOptional
Due date of invoice.
feesobjectOptional
If using a custom payment method, you can override the default fees for this invoice. If not provided, the default fees for the custom payment method will be used.
invoiceDatedatetimeOptional
Date the invoice was issued.
invoiceNumberstringOptional
lineItemslist of objectsOptional
metadatamap from strings to stringsOptional
Metadata associated with this invoice.
noteToSelfstringOptional
Note to self or memo on invoice.
payerIdstringOptional
ID or foreign ID of the payer of this invoice.
paymentDestinationIdstringOptional
ID of payment destination for this invoice. If not provided, will attempt to use the default payment destination for the vendor when creating an invoice if a default payment destination exists for the vendor.
paymentDestinationOptionsobjectOptional
Options for the payment destination. Depending on the payment destination, this may include things such as check delivery method.
paymentScheduleobjectOptional
If this is a recurring invoice, this will be the payment schedule for the invoice. If not provided, this will be a one-time invoice.
paymentSourceIdstringOptional
ID of payment source for this invoice. If not provided, will attempt to use the default payment source for the payer when creating an invoice if a default payment source exists for the payer.
serviceEndDatedatetimeOptional
serviceStartDatedatetimeOptional
shippingAmountdoubleOptional
Shipping amount for this invoice.
statusenumOptional
taxAmountdoubleOptional
Tax amount for this invoice.
vendorIdstringOptional
ID or foreign ID of the vendor of this invoice.

Response

This endpoint returns an object.
approvalPolicylist of objects
approverslist of objects
createdAtdatetime
hasDocumentsboolean
True if the invoice has documents attached.
hasSourceEmailboolean
True if the invoice was created by an incoming email.
idstring
metadatamap from strings to strings
Metadata associated with this invoice.
paymentDestinationConfirmedboolean
True if the payment destination has been confirmed by the vendor. False if the payment destination has been set (for example, a check to an address) but has not been confirmed by the vendor.
statusenum
updatedAtdatetime
amountdouble or null
Total amount of invoice in major units
batchPaymentboolean or null
If true, this invoice will be paid as a batch payment. Batches are automatically determined by Mercoa based on the payment source, destination, and scheduled payment date.
commentslist of objects or null
creatorEntityIdstring or null
The ID of the entity who created this invoice.
creatorUserobject or null
Entity user who created this invoice.
currencyenum or null
Currency code for the amount. Defaults to USD.
deductionDatedatetime or null
Initial date when funds are scheduled to be deducted from payer's account. The actual deduction date may differ from this date, and will be reflected in the processedAt field.
dueDatedatetime or null
Due date of invoice.
feesobject or null
Fees associated with this invoice.
invoiceDatedatetime or null
Date the invoice was issued.
invoiceNumberstring or null
lineItemslist of objects or null
netTermsinteger or null
Net terms in days. Must be a positive number.
nextDeductionDatedatetime or null
For invoice templates, this is the date when the next recurring payment will be scheduled.
noteToSelfstring or null
ocrJobIdstring or null
ID of the OCR job that processed this invoice.
payerobject or null
payerIdstring or null
paymentDestinationobject or null
paymentDestinationIdstring or null
paymentDestinationOptionsobject or null
paymentScheduleobject or null
If this is a recurring invoice, this will be the payment schedule for the invoice. If not provided, this will be a one-time invoice.
paymentSourceobject or null
paymentSourceIdstring or null
paymentSourceOptionsobject or null
paymentTimingobject or null
recurringTemplateIdstring or null
ID of the invoice template that created this recurring invoice. Only present if the invoice was created from a recurring template.
serviceEndDatedatetime or null
serviceStartDatedatetime or null
shippingAmountdouble or null
Shipping amount for this invoice.
taxAmountdouble or null
Tax amount for this invoice.
vendorobject or null
vendorIdstring or null

Errors

If this is a recurring invoice, this will be the payment schedule for the invoice. If not provided, this will be a one-time invoice.

True if the payment destination has been confirmed by the vendor. False if the payment destination has been set (for example, a check to an address) but has not been confirmed by the vendor.

If this is a recurring invoice, this will be the payment schedule for the invoice. If not provided, this will be a one-time invoice.

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

Base64-encoded string. Supported file types include PNG, JPG, WEBP, PDF, and all Microsoft Office formats (automatically converted to PDF). Max file size 10MB.