Invoice

Update

POST

Path parameters

invoiceIdstringRequired

Request

This endpoint expects an object.
amount
doubleOptional
Total amount of invoice in major units. If the entered amount has more decimal places than the currency supports, trailing decimals will be truncated.
approvers
list of objectsOptional
Set approvers for this invoice.
creatorEntityId
stringOptional
ID of entity who created this invoice. If creating a payable invoice (AP), this must be the same as the payerId. If creating a receivable invoice (AR), this must be the same as the vendorId.
creatorUserId
stringOptional
ID of entity user who created this invoice.
currency
enumOptional
Currency code for the amount. Defaults to USD.
deductionDate
datetimeOptional
Date when funds will be deducted from payer's account.
document
stringOptional
Base64 encoded image or PDF of invoice document. PNG, JPG, and PDF are supported. 10MB max. If the invoice already has a document, this will add a new document to the invoice.
dueDate
datetimeOptional
Due date of invoice.
foreignId
stringOptional
The ID used to identify this invoice in your system. This ID must be unique within each creatorEntity in your system, e.g. two invoices with the same creatorEntity may not have the same foreign ID.
invoiceDate
datetimeOptional
Date the invoice was issued.
invoiceNumber
stringOptional
lineItems
list of objectsOptional
metadata
map from strings to stringsOptional
Metadata associated with this invoice. You can specify up to 10 keys, with key names up to 40 characters long and values up to 200 characters long.
noteToSelf
stringOptional
Note to self or memo on invoice.
payerId
stringOptional
paymentDestinationId
stringOptional
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.
paymentDestinationOptions
unionOptional
Options for the payment destination. Depending on the payment destination, this may include things such as check delivery method.
paymentSourceId
stringOptional
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.
serviceEndDate
datetimeOptional
serviceStartDate
datetimeOptional
settlementDate
datetimeOptional
Date of funds settlement.
status
enumOptional
vendorId
stringOptional
uploadedImage
stringOptional
Deprecated
DEPRECATED. Use document field instead.

Response

This endpoint returns an object
id
string
status
enum
paymentDestinationConfirmed
boolean
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.
hasDocuments
boolean
True if the invoice has documents attached.
hasSourceEmail
boolean
True if the invoice was created by an incoming email.
approvers
list of objects
approvalPolicy
list of objects
metadata
map from strings to strings
Metadata associated with this invoice.
createdAt
datetime
updatedAt
datetime
amount
doubleOptional
Total amount of invoice in major units
currency
enumOptional
Currency code for the amount. Defaults to USD.
invoiceDate
datetimeOptional
Date the invoice was issued.
deductionDate
datetimeOptional
Date when funds will be deducted from payer's account.
settlementDate
datetimeOptional
Date of funds settlement.
dueDate
datetimeOptional
Due date of invoice.
invoiceNumber
stringOptional
noteToSelf
stringOptional
serviceStartDate
datetimeOptional
serviceEndDate
datetimeOptional
payerId
stringOptional
payer
objectOptional
paymentSource
unionOptional
paymentSourceId
stringOptional
vendorId
stringOptional
vendor
objectOptional
paymentDestination
unionOptional
paymentDestinationId
stringOptional
paymentDestinationOptions
unionOptional
comments
list of objectsOptional
lineItems
list of objectsOptional
foreignId
stringOptional
The ID used to identify this invoice in your system. This ID must be unique within each creatorEntity in your system, e.g. two invoices with the same creatorEntity may not have the same foreign ID.
creatorUser
objectOptional
Entity user who created this invoice.
failureType
enumOptional
If the invoice failed to be paid, this field will be populated with the type of failure.
Allowed values: SOURCE_PAYMENT_ERRORDESTINATION_PAYMENT_ERRORREJECTED_HIGH_RISKINSUFFICIENT_FUNDSPROCESSING_ERROR
processedAt
datetimeOptional
fees
objectOptional
Fees associated with this invoice.
POST
1curl -X POST https://api.mercoa.com/invoice/inv_8545a84e-a45f-41bf-bdf1-33b42a55812c \
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  "dueDate": "2021-01-31T00:00:00Z",
10  "invoiceDate": "2021-01-01T00:00:00Z",
11  "invoiceNumber": "INV-123",
12  "lineItems": [
13    {
14      "amount": 100,
15      "description": "Product A",
16      "currency": "USD",
17      "name": "Product A",
18      "quantity": 1,
19      "unitPrice": 100,
20      "serviceStartDate": "2021-01-01T00:00:00Z",
21      "serviceEndDate": "2021-01-31T00:00:00Z",
22      "metadata": {
23        "key1": "value1",
24        "key2": "value2"
25      },
26      "glAccountId": "600394"
27    }
28  ],
29  "noteToSelf": "For the month of January",
30  "payerId": "ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
31  "paymentDestinationId": "pm_5fde2f4a-facc-48ef-8f0d-6b7d087c7b18",
32  "paymentDestinationOptions": {
33    "type": "check",
34    "delivery": "MAIL"
35  },
36  "paymentSourceId": "pm_4794d597-70dc-4fec-b6ec-c5988e759769",
37  "serviceEndDate": "2021-01-31T00:00:00Z",
38  "serviceStartDate": "2021-01-01T00:00:00Z",
39  "status": "DRAFT",
40  "vendorId": "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d"
41}'
200
Successful
1{
2  "id": "inv_26e7b5d3-a739-4b23-9ad9-6aaa085f47a9",
3  "status": "PAID",
4  "paymentDestinationConfirmed": true,
5  "hasDocuments": true,
6  "hasSourceEmail": true,
7  "approvers": [
8    {
9      "approvalPolicyId": "apvl_5ce50275-1789-42ea-bc60-bb7e6d03635c",
10      "approvalSlotId": "inap_9bb311c9-7c15-4c9e-8148-63814e0abec6",
11      "action": "APPROVE",
12      "eligibleRoles": [
13        "admin"
14      ],
15      "eligibleUserIds": [
16        "user_e24fc81c-c5ee-47e8-af42-4fe29d895506"
17      ],
18      "date": "2021-01-01T00:00:00Z",
19      "assignedUserId": "user_e24fc81c-c5ee-47e8-af42-4fe29d895506"
20    }
21  ],
22  "approvalPolicy": [
23    {
24      "id": "apvl_8545a84e-a45f-41bf-bdf1-33b42a55812c",
25      "trigger": [],
26      "rule": {
27        "type": "approver",
28        "identifierList": {
29          "type": "rolesList",
30          "value": [
31            "admin"
32          ]
33        },
34        "numApprovers": 1
35      },
36      "upstreamPolicyId": "root"
37    }
38  ],
39  "metadata": {
40    "key1": "value1",
41    "key2": "value2"
42  },
43  "createdAt": "2021-01-01T00:00:00Z",
44  "updatedAt": "2021-01-01T00:00:00Z",
45  "amount": 100,
46  "currency": "USD",
47  "invoiceDate": "2021-01-01T00:00:00Z",
48  "deductionDate": "2021-01-01T00:00:00Z",
49  "settlementDate": "2021-01-03T00:00:00Z",
50  "dueDate": "2021-01-31T00:00:00Z",
51  "invoiceNumber": "INV-123",
52  "noteToSelf": "For the month of January",
53  "serviceStartDate": "2021-01-01T00:00:00Z",
54  "serviceEndDate": "2021-01-31T00:00:00Z",
55  "payerId": "ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
56  "payer": {
57    "id": "ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
58    "name": "Acme Inc.",
59    "email": "customer@acme.com",
60    "isCustomer": true,
61    "accountType": "business",
62    "profile": {
63      "business": {
64        "legalBusinessName": "Acme Inc.",
65        "taxIDProvided": true,
66        "email": "customer@acme.com",
67        "businessType": "llc",
68        "phone": {
69          "countryCode": "1",
70          "number": "4155551234"
71        },
72        "address": {
73          "addressLine1": "123 Main St",
74          "city": "San Francisco",
75          "stateOrProvince": "CA",
76          "postalCode": "94105",
77          "addressLine2": "Unit 1",
78          "country": "US"
79        },
80        "ownersProvided": true
81      }
82    },
83    "status": "verified",
84    "acceptedTos": true,
85    "isPayor": true,
86    "isPayee": false,
87    "createdAt": "2024-01-01T00:00:00Z",
88    "updatedAt": "2024-01-02T00:00:00Z",
89    "foreignId": "MY-DB-ID-12345"
90  },
91  "paymentSource": {
92    "type": "bankAccount",
93    "accountName": "My Checking Account",
94    "accountNumber": "99988767623",
95    "accountType": "CHECKING",
96    "bankName": "Chase",
97    "createdAt": "2021-01-01T00:00:00Z",
98    "id": "pm_4794d597-70dc-4fec-b6ec-c5988e759769",
99    "isDefaultDestination": true,
100    "isDefaultSource": true,
101    "routingNumber": "12345678",
102    "status": "VERIFIED",
103    "supportedCurrencies": [
104      "USD"
105    ],
106    "updatedAt": "2021-01-01T00:00:00Z"
107  },
108  "paymentSourceId": "pm_4794d597-70dc-4fec-b6ec-c5988e759769",
109  "vendorId": "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d",
110  "vendor": {
111    "id": "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d",
112    "name": "Big Box Store",
113    "email": "vendor@bigboxstore.com",
114    "isCustomer": false,
115    "accountType": "business",
116    "profile": {
117      "business": {
118        "legalBusinessName": "Big Box Store",
119        "taxIDProvided": false,
120        "email": "vendor@bigboxstore.com",
121        "businessType": "publicCorporation",
122        "ownersProvided": false
123      }
124    },
125    "status": "unverified",
126    "acceptedTos": false,
127    "isPayor": false,
128    "isPayee": true,
129    "createdAt": "2024-01-01T00:00:00Z",
130    "updatedAt": "2024-01-02T00:00:00Z",
131    "foreignId": "MY-DB-ID-90909"
132  },
133  "paymentDestination": {
134    "type": "check",
135    "addressLine1": "123 Main St",
136    "city": "New York",
137    "country": "US",
138    "createdAt": "2021-01-01T00:00:00Z",
139    "id": "pm_5fde2f4a-facc-48ef-8f0d-6b7d087c7b18",
140    "isDefaultDestination": true,
141    "isDefaultSource": false,
142    "payToTheOrderOf": "John Doe",
143    "postalCode": "10001",
144    "stateOrProvince": "NY",
145    "supportedCurrencies": [
146      "USD"
147    ],
148    "updatedAt": "2021-01-01T00:00:00Z",
149    "addressLine2": "Apt 1"
150  },
151  "paymentDestinationId": "pm_5fde2f4a-facc-48ef-8f0d-6b7d087c7b18",
152  "paymentDestinationOptions": {
153    "type": "check",
154    "delivery": "MAIL"
155  },
156  "comments": [
157    {
158      "id": "ic_b3525b66-da94-4525-9f31-426bcf657128",
159      "text": "This is a comment",
160      "createdAt": "2021-01-01T00:00:00Z",
161      "updatedAt": "2021-01-01T00:00:00Z",
162      "user": {
163        "id": "user_ec3aafc8-ea86-408a-a6c1-545497badbbb",
164        "roles": [
165          "admin",
166          "approver"
167        ],
168        "createdAt": "2024-01-01T00:00:00Z",
169        "updatedAt": "2024-01-01T00:00:00Z",
170        "foreignId": "MY-DB-ID-12345",
171        "email": "john.doe@acme.com",
172        "name": "John Doe"
173      },
174      "associatedApprovalAction": {
175        "userId": "user_e24fc81c-c5ee-47e8-af42-4fe29d895506",
176        "action": "APPROVE"
177      }
178    }
179  ],
180  "lineItems": [
181    {
182      "id": "inli_26672f38-eb9a-48f1-a7a0-f1b855e38cd7",
183      "currency": "USD",
184      "createdAt": "2021-01-01T00:00:00Z",
185      "updatedAt": "2021-01-01T00:00:00Z",
186      "amount": 100,
187      "description": "Product A",
188      "name": "Product A",
189      "quantity": 1,
190      "unitPrice": 100,
191      "serviceStartDate": "2021-01-01T00:00:00Z",
192      "serviceEndDate": "2021-01-31T00:00:00Z",
193      "metadata": {
194        "key1": "value1",
195        "key2": "value2"
196      },
197      "glAccountId": "600394"
198    }
199  ],
200  "foreignId": "YOUR-DATABASE-ID",
201  "creatorUser": {
202    "id": "user_ec3aafc8-ea86-408a-a6c1-545497badbbb",
203    "roles": [
204      "admin",
205      "approver"
206    ],
207    "createdAt": "2024-01-01T00:00:00Z",
208    "updatedAt": "2024-01-01T00:00:00Z",
209    "foreignId": "MY-DB-ID-12345",
210    "email": "john.doe@acme.com",
211    "name": "John Doe"
212  },
213  "processedAt": "2021-01-01T00:00:00Z"
214}
Built with