EntityInvoice

Get

GET
https://api.mercoa.com/entity/:entityId/invoice/:invoiceId

Path parameters

entityId
string
invoiceId
string

ID of the invoice to retrieve. This can be the full invoice ID (in_11aa2b77-6391-49e4-8c3f-b198009202c1) or the first 8 characters of the ID (11aa2b77).

Query parameters

includeFees
optional boolean

DEPRECATED. Fees are now included by default in the response.

Response

This endpoint return 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.

approvers
list of objects
approvalPolicy
list of objects
metadata
map from strings to strings

Metadata associated with this invoice.

createdAt
datetime
updatedAt
datetime
amount
optional double

Total amount of invoice in major units

currency
optional enum

Currency code for the amount. Defaults to USD.

invoiceDate
optional datetime

Date the invoice was issued.

deductionDate
optional datetime

Date when funds will be deducted from payer's account.

settlementDate
optional datetime

Date of funds settlement.

dueDate
optional datetime

Due date of invoice.

invoiceNumber
optional string
noteToSelf
optional string
serviceStartDate
optional datetime
serviceEndDate
optional datetime
payerId
optional string
payer
optional object
paymentSource
optional union
paymentSourceId
optional string
vendorId
optional string
vendor
optional object
paymentDestination
optional union
paymentDestinationId
optional string
paymentDestinationOptions
optional union
comments
optional list of objects
lineItems
optional list of objects
foreignId
optional string

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
optional object

Entity user who created this invoice.

failureType
optional enum

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
optional datetime
fees
optional object

Fees associated with this invoice.

GET
/entity/:entityId/invoice/:invoiceId
curl -G https://api.mercoa.com/entity/:entityId/invoice/:invoiceId \
-H "Authorization: Bearer <token>" \
-d includeFees=true
Response
{
"id": "string",
"status": "DRAFT",
"paymentDestinationConfirmed": true,
"hasDocuments": true,
"approvers": [
{
"approvalPolicyId": "string",
"approvalSlotId": "string",
"action": "NONE",
"eligibleRoles": [
"string"
],
"eligibleUserIds": [
"string"
],
"date": "2023-01-01T00:00:00Z",
"assignedUserId": "string"
}
],
"approvalPolicy": [
{
"id": "string",
"trigger": [
{
"type": "amount",
"amount": 1,
"currency": "AED"
}
],
"rule": {
"type": "approver",
"identifierList": {
"type": "rolesList",
"value": [
"string"
]
},
"numApprovers": 0
},
"upstreamPolicyId": "string"
}
],
"metadata": {
"string": "string"
},
"createdAt": "2023-01-01T00:00:00Z",
"updatedAt": "2023-01-01T00:00:00Z",
"amount": 1,
"currency": "AED",
"invoiceDate": "2023-01-01T00:00:00Z",
"deductionDate": "2023-01-01T00:00:00Z",
"settlementDate": "2023-01-01T00:00:00Z",
"dueDate": "2023-01-01T00:00:00Z",
"invoiceNumber": "string",
"noteToSelf": "string",
"serviceStartDate": "2023-01-01T00:00:00Z",
"serviceEndDate": "2023-01-01T00:00:00Z",
"payerId": "string",
"payer": {
"id": "string",
"name": "string",
"email": "string",
"isCustomer": true,
"accountType": "business",
"profile": {
"business": {
"legalBusinessName": "string",
"taxIDProvided": true,
"email": "string",
"businessType": "soleProprietorship",
"phone": {
"countryCode": "string",
"number": "string"
},
"doingBusinessAs": "string",
"website": "string",
"description": "string",
"address": {
"addressLine1": "string",
"city": "string",
"stateOrProvince": "string",
"postalCode": "string",
"addressLine2": "string",
"country": "string"
},
"ownersProvided": true
},
"individual": {
"email": "string",
"name": {
"firstName": "string",
"lastName": "string",
"middleName": "string",
"suffix": "string"
},
"birthDateProvided": true,
"governmentIDProvided": true,
"phone": {
"countryCode": "string",
"number": "string"
},
"address": {
"addressLine1": "string",
"city": "string",
"stateOrProvince": "string",
"postalCode": "string",
"addressLine2": "string",
"country": "string"
}
}
},
"status": "unverified",
"acceptedTos": true,
"isPayor": true,
"isPayee": true,
"createdAt": "2023-01-01T00:00:00Z",
"updatedAt": "2023-01-01T00:00:00Z",
"foreignId": "string",
"emailTo": "string",
"emailToAlias": [
"string"
]
},
"paymentSource": {
"type": "bankAccount",
"accountName": "string",
"accountNumber": "string",
"accountType": "CHECKING",
"bankName": "string",
"createdAt": "2023-01-01T00:00:00Z",
"id": "string",
"isDefaultDestination": true,
"isDefaultSource": true,
"routingNumber": "string",
"status": "NEW",
"supportedCurrencies": [
"AED"
],
"updatedAt": "2023-01-01T00:00:00Z",
"checkOptions": {
"enabled": true,
"initialCheckNumber": 0,
"routingNumberOverride": "string",
"accountNumberOverride": "string",
"signatoryName": "string",
"signatureImage": "string"
}
},
"paymentSourceId": "string",
"vendorId": "string",
"vendor": {
"id": "string",
"name": "string",
"email": "string",
"isCustomer": true,
"accountType": "business",
"profile": {
"business": {
"legalBusinessName": "string",
"taxIDProvided": true,
"email": "string",
"businessType": "soleProprietorship",
"phone": {
"countryCode": "string",
"number": "string"
},
"doingBusinessAs": "string",
"website": "string",
"description": "string",
"address": {
"addressLine1": "string",
"city": "string",
"stateOrProvince": "string",
"postalCode": "string",
"addressLine2": "string",
"country": "string"
},
"ownersProvided": true
},
"individual": {
"email": "string",
"name": {
"firstName": "string",
"lastName": "string",
"middleName": "string",
"suffix": "string"
},
"birthDateProvided": true,
"governmentIDProvided": true,
"phone": {
"countryCode": "string",
"number": "string"
},
"address": {
"addressLine1": "string",
"city": "string",
"stateOrProvince": "string",
"postalCode": "string",
"addressLine2": "string",
"country": "string"
}
}
},
"status": "unverified",
"acceptedTos": true,
"isPayor": true,
"isPayee": true,
"createdAt": "2023-01-01T00:00:00Z",
"updatedAt": "2023-01-01T00:00:00Z",
"foreignId": "string",
"emailTo": "string",
"emailToAlias": [
"string"
]
},
"paymentDestination": {
"type": "bankAccount",
"accountName": "string",
"accountNumber": "string",
"accountType": "CHECKING",
"bankName": "string",
"createdAt": "2023-01-01T00:00:00Z",
"id": "string",
"isDefaultDestination": true,
"isDefaultSource": true,
"routingNumber": "string",
"status": "NEW",
"supportedCurrencies": [
"AED"
],
"updatedAt": "2023-01-01T00:00:00Z",
"checkOptions": {
"enabled": true,
"initialCheckNumber": 0,
"routingNumberOverride": "string",
"accountNumberOverride": "string",
"signatoryName": "string",
"signatureImage": "string"
}
},
"paymentDestinationId": "string",
"paymentDestinationOptions": {
"type": "check",
"delivery": "PRINT"
},
"comments": [
{
"id": "string",
"text": "string",
"createdAt": "2023-01-01T00:00:00Z",
"updatedAt": "2023-01-01T00:00:00Z",
"user": {
"id": "string",
"roles": [
"string"
],
"createdAt": "2023-01-01T00:00:00Z",
"updatedAt": "2023-01-01T00:00:00Z",
"foreignId": "string",
"email": "string",
"name": "string"
},
"associatedApprovalAction": {
"userId": "string",
"action": "NONE"
}
}
],
"lineItems": [
{
"id": "string",
"currency": "AED",
"createdAt": "2023-01-01T00:00:00Z",
"updatedAt": "2023-01-01T00:00:00Z",
"amount": 1,
"description": "string",
"name": "string",
"quantity": 0,
"unitPrice": 1,
"serviceStartDate": "2023-01-01T00:00:00Z",
"serviceEndDate": "2023-01-01T00:00:00Z",
"metadata": {
"string": "string"
},
"glAccountId": "string"
}
],
"foreignId": "string",
"creatorUser": {
"id": "string",
"roles": [
"string"
],
"createdAt": "2023-01-01T00:00:00Z",
"updatedAt": "2023-01-01T00:00:00Z",
"foreignId": "string",
"email": "string",
"name": "string"
},
"failureType": "SOURCE_PAYMENT_ERROR",
"processedAt": "2023-01-01T00:00:00Z",
"fees": {
"sourcePaymentMethodFee": 1,
"sourcePlatformMarkupFee": 1,
"destinationPaymentMethodFee": 1,
"destinationPlatformMarkupFee": 1
}
}