> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.mercoa.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mercoa.com/_mcp/server. # Events GET https://api.mercoa.com/invoice/{invoiceId}/events Get all events for an invoice Reference: https://docs.mercoa.com/embedded-ap-ar/api-reference/invoice/events ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Path parameters - `invoiceId` (string, required) — Invoice ID or Invoice ForeignID ### Query parameters - `startDate` (datetime, optional) — Start date filter. If not provided, events from the start of time will be returned. - `endDate` (datetime, optional) — End date filter. If not provided, events to the end of time will be returned. - `limit` (integer, optional) — Number of events to return. Limit can range between 1 and 100, and the default is 50. - `startingAfter` (string, optional) — The ID of the event to start after. If not provided, the first page of events will be returned. ## Response ### 200 - `data` (list of object, required) - `id` (string, required) — The ID of the event - `data` (object, required) — The data related to the invoice update - `amount` (double, optional) — 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 object, optional) — Set approvers for this invoice. - `approvalSlotId` (string, required) — The identifier for the approval slot this user is assigned to. - `assignedUserId` (string, required) — The ID of the user who is assigned to the approval slot. To assign all eligible users to an approval slot, use "ANY". - `batchPayment` (boolean, optional) — 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. - `creatorEntityId` (string, optional) — ID or foreign 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` (string, optional) — User ID or Foreign ID of entity user who created this invoice. - `currency` (enum, optional) — Currency code for the amount. Defaults to USD. - Allowed values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `CNY`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL` - `deductionDate` (datetime, optional) — Initial date when funds are scheduled to be deducted from payer's account. - `document` (string, optional) — Base64-encoded string. Supported file types include PNG, JPG, WEBP, PDF, and all Microsoft Office formats (automatically converted to PDF). Max file size 10MB. If the invoice already has a document, this will add a new document to the invoice. - `dueDate` (datetime, optional) — Due date of invoice. - `failureType` (enum, optional) — If the invoice failed to be paid, indicate the failure reason. Only applicable for invoices with custom payment methods. - Allowed values: `SOURCE_PAYMENT_ERROR`, `DESTINATION_PAYMENT_ERROR`, `REJECTED_HIGH_RISK`, `INSUFFICIENT_FUNDS`, `PROCESSING_ERROR` - `fees` (object, optional) — 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. - `sourcePlatformMarkupFee` (double, required) — Fee charged to the payer (C2). - `destinationPlatformMarkupFee` (double, required) — Fee charged to the payee (C3). - `foreignId` (string, optional) — 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` (datetime, optional) — Date the invoice was issued. - `invoiceNumber` (string, optional) - `lineItems` (list of object, optional) - `amount` (double, optional) — Total amount of line item in major units. If the entered amount has more decimal places than the currency supports, trailing decimals will be truncated. - `category` (string, optional) — Category of the line item. - `currency` (enum, optional) — Currency code for the amount. Defaults to USD. - Allowed values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `CNY`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL` - `description` (string, optional) - `glAccountId` (string, optional) — ID of general ledger account associated with this line item. - `id` (string, optional) — If provided, will overwrite line item on the invoice with this ID. If not provided, will create a new line item. - `metadata` (map from string to string, optional) - `name` (string, optional) - `quantity` (double, optional) - `serviceEndDate` (datetime, optional) - `serviceStartDate` (datetime, optional) - `unitPrice` (double, optional) — Unit price of the line item in major units. If the entered amount has more decimal places than the currency supports, trailing decimals will be truncated. - `metadata` (map from string to string, optional) — Metadata associated with this invoice. - `netTerms` (integer, optional) — Net terms in days. Must be a positive number. - `noteToSelf` (string, optional) — Note to self or memo on invoice. - `ocrJobId` (string, optional) — ID of the OCR job that processed this invoice. - `payerId` (string, optional) — ID or foreign ID of the payer of this invoice. - `paymentDestinationConfirmed` (boolean, optional) — Set to true if the payment destination has been confirmed by the vendor or if the payment destination should default to the selected payment destination on the vendor portal. - `paymentDestinationId` (string, optional) — 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` (object, optional) — Options for the payment destination. Depending on the payment destination, this may include things such as check delivery method. - `type`: `check` - `delivery` (enum, optional) — Delivery method for check disbursements. Defaults to MAIL. - Allowed values: `PRINT`, `MAIL`, `MAIL_PRIORITY`, `MAIL_UPS_NEXT_DAY` - `printDescription` (boolean, optional) — If true, prints the invoice description (noteToSelf) on the check note. Defaults to false. - `type`: `bankAccount` - `delivery` (enum, optional) — Delivery method for ACH payments. Defaults to ACH_SAME_DAY. - Allowed values: `ACH_STANDARD`, `ACH_SAME_DAY`, `ACH_ACCELERATED` - `description` (string, optional) — ACH Statement Description. By default, this will be 'AP' followed by the first 8 characters of the invoice ID (for a single invoice) or the first 8 characters of the transaction ID (for a batch payment). Must be at least 4 characters and no more than 10 characters, and follow this regex pattern `^[a-zA-Z0-9\-#.$&* ]{4,10}$` - `type`: `utility` - `accountId` (string, required) — The ID for the utility account to pay with. Links to accounts listed on payor/payee relationship. - `type`: `custom` - `dynamicUrls` (map from string to string, optional) — Map of field names to dynamic URL values that will be used for dynamicUrl fields in custom payment method schemas - `paymentSchedule` (object, optional) — 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. - `type`: `oneTime` - `ends` (integer or datetime, optional) — When to end the payments, either a number of occurrences or a date. Defaults to never ending if not specified - `repeatEvery` (integer, optional) — How often to repeat the payments. Defaults to 1. Must be greater than 0. For example, if repeatEvery is set to 2 and this is a daily payment, the payment will be made every other day. If repeatEvery is set to 3 and this is a weekly payment, the payment will be made every third week. - `type`: `daily` - `ends` (integer or datetime, optional) — When to end the payments, either a number of occurrences or a date. Defaults to never ending if not specified - `repeatEvery` (integer, optional) — How often to repeat the payments. Defaults to 1. Must be greater than 0. For example, if repeatEvery is set to 2 and this is a daily payment, the payment will be made every other day. If repeatEvery is set to 3 and this is a weekly payment, the payment will be made every third week. - `type`: `weekly` - `repeatOn` (list of enum, required) - Allowed values: `0`, `1`, `2`, `3`, `4`, `5`, `6` - `ends` (integer or datetime, optional) — When to end the payments, either a number of occurrences or a date. Defaults to never ending if not specified - `repeatEvery` (integer, optional) — How often to repeat the payments. Defaults to 1. Must be greater than 0. For example, if repeatEvery is set to 2 and this is a daily payment, the payment will be made every other day. If repeatEvery is set to 3 and this is a weekly payment, the payment will be made every third week. - `type`: `monthly` - `repeatOnDay` (integer, required) — Day of the month to repeat on. Positive values (1-31): Represent the day of the month counting from the start (e.g., 10 is the 10th day of the month). Negative values (-1 to -31): Represent the day of the month counting backward from the end (e.g., -1 is the last day of the month, -2 is the second-to-last day). - `ends` (integer or datetime, optional) — When to end the payments, either a number of occurrences or a date. Defaults to never ending if not specified - `repeatEvery` (integer, optional) — How often to repeat the payments. Defaults to 1. Must be greater than 0. For example, if repeatEvery is set to 2 and this is a daily payment, the payment will be made every other day. If repeatEvery is set to 3 and this is a weekly payment, the payment will be made every third week. - `dayOffset` (integer, optional, deprecated) — deprecated. will be removed in the future and will always be 0. - `type`: `yearly` - `repeatOnDay` (integer, required) — Day of the month to repeat on. Positive values (1-31): Represent the day of the month counting from the start (e.g., 10 is the 10th day of the month). Negative values (-1 to -31): Represent the day of the month counting backward from the end (e.g., -1 is the last day of the month, -2 is the second-to-last day). - `repeatOnMonth` (integer, required) — Month to repeat on (1-12). - `ends` (integer or datetime, optional) — When to end the payments, either a number of occurrences or a date. Defaults to never ending if not specified - `repeatEvery` (integer, optional) — How often to repeat the payments. Defaults to 1. Must be greater than 0. For example, if repeatEvery is set to 2 and this is a daily payment, the payment will be made every other day. If repeatEvery is set to 3 and this is a weekly payment, the payment will be made every third week. - `paymentSourceId` (string, optional) — 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. - `paymentSourceOptions` (object, optional) — Options for the payment source. Depending on the payment source, this may include things such as BNPL configuration. - `type`: `bnpl` - `acceptedTerms` (boolean, required) — Whether the user has agreed to the BNPL terms - `defermentWeeks` (integer, required) — The number of weeks to defer repayment - `installmentsStartDate` (string, required) — The start date for installments in YYYY-MM-DD format - `downpaymentId` (string, optional) — The ID of the downpayment to use for the BNPL payment. - `loanId` (string, optional) — The ID of the loan to use for the BNPL payment. - `serviceEndDate` (datetime, optional) - `serviceStartDate` (datetime, optional) - `settlementDate` (datetime, optional) — Date of funds settlement. - `shippingAmount` (double, optional) — Shipping amount for this invoice. - `status` (enum, optional) - Allowed values: `UNASSIGNED`, `DRAFT`, `NEW`, `APPROVED`, `SCHEDULED`, `PENDING`, `PAID`, `ARCHIVED`, `REFUSED`, `CANCELED`, `FAILED` - `taxAmount` (double, optional) — Tax amount for this invoice. - `vendorCreditIds` (list of string, optional) — The IDs of the vendor credits to be applied to this invoice. Passing this field will un-apply any previously applied vendor credits. - `vendorId` (string, optional) — ID or foreign ID of the vendor of this invoice. - `uploadedImage` (string, optional, deprecated) — DEPRECATED. Use document field instead. - `webhookIds` (list of string, required) — The list of webhook IDs associated with this event - `createdAt` (datetime, required) — The timestamp when the event was created - `status` (enum, optional) — The current status of the invoice event - Allowed values: `UNASSIGNED`, `DRAFT`, `NEW`, `APPROVED`, `SCHEDULED`, `PENDING`, `PAID`, `ARCHIVED`, `REFUSED`, `CANCELED`, `FAILED` - `userId` (string, optional) — The ID of the user who triggered this event - `ipAddress` (string, optional) — The IP address of the user who triggered the event - `count` (integer, required) - `hasMore` (boolean, required) ## Errors ### 400 Bad Request - `errorName` ("BadRequest", required) - `content` (string, required) ### 401 Unauthorized - `errorName` ("Unauthorized", required) - `content` (string, required) ### 403 Forbidden - `errorName` ("Forbidden", required) - `content` (string, required) ### 404 Not Found - `errorName` ("NotFound", required) - `content` (string, required) ### 409 Conflict - `errorName` ("Conflict", required) - `content` (string, required) ### 500 Internal Server Error - `errorName` ("InternalServerError", required) - `content` (string, required) ### 501 Unimplemented - `errorName` ("Unimplemented", required) - `content` (string, required) ## Examples **Response** ```json { "data": [ { "id": "evt_a0f6ea94-0761-4a5e-a416-3c453cb7eced", "data": { "amount": 100, "creatorEntityId": "ent_8545a84e-a45f-41bf-bdf1-33b42a55812c", "creatorUserId": "user_e24fc81c-c5ee-47e8-af42-4fe29d895506", "currency": "USD", "dueDate": "2021-01-31T00:00:00Z", "invoiceDate": "2021-01-01T00:00:00Z", "invoiceNumber": "INV-123", "lineItems": [ { "amount": 100, "category": "EXPENSE", "currency": "USD", "description": "Product A", "glAccountId": "600394", "id": "inli_26672f38-eb9a-48f1-a7a0-f1b855e38cd7", "metadata": { "key1": "value1", "key2": "value2" }, "name": "Product A", "quantity": 1, "serviceEndDate": "2021-01-31T00:00:00Z", "serviceStartDate": "2021-01-01T00:00:00Z", "unitPrice": 100 } ], "noteToSelf": "For the month of January", "payerId": "ent_8545a84e-a45f-41bf-bdf1-33b42a55812c", "paymentDestinationId": "pm_5fde2f4a-facc-48ef-8f0d-6b7d087c7b18", "paymentDestinationOptions": { "type": "check", "delivery": "MAIL", "printDescription": true }, "paymentSourceId": "pm_4794d597-70dc-4fec-b6ec-c5988e759769", "status": "NEW", "vendorId": "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d" }, "webhookIds": [ "webhook_12345" ], "createdAt": "2024-01-01T00:00:00.000Z", "userId": "user_e24fc81c-c5ee-47e8-af42-4fe29d895506" } ], "count": 1, "hasMore": false } ``` **SDK Code** ```python Default import requests url = "https://api.mercoa.com/invoice/in_8545a84e-a45f-41bf-bdf1-33b42a55812c/events" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```typescript Default import { MercoaClient } from "@mercoa/javascript"; const client = new MercoaClient({ token: "YOUR_TOKEN" }); await client.invoice.events("in_8545a84e-a45f-41bf-bdf1-33b42a55812c"); ``` ```go Default package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.mercoa.com/invoice/in_8545a84e-a45f-41bf-bdf1-33b42a55812c/events" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Default require 'uri' require 'net/http' url = URI("https://api.mercoa.com/invoice/in_8545a84e-a45f-41bf-bdf1-33b42a55812c/events") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java Default import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.mercoa.com/invoice/in_8545a84e-a45f-41bf-bdf1-33b42a55812c/events") .header("Authorization", "Bearer ") .asString(); ``` ```php Default request('GET', 'https://api.mercoa.com/invoice/in_8545a84e-a45f-41bf-bdf1-33b42a55812c/events', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp Default using RestSharp; var client = new RestClient("https://api.mercoa.com/invoice/in_8545a84e-a45f-41bf-bdf1-33b42a55812c/events"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift Default import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.mercoa.com/invoice/in_8545a84e-a45f-41bf-bdf1-33b42a55812c/events")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```