Mercury: Invoices schemas
9 Mercury schemas with complete fields and constraints.
← Invoices operations · All schemas
Create an invoice — request body — body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | The request body to create an invoice. Additional keys: not allowed |
achDebitEnabled | boolean | Required within parent | Whether or not the invoice can be paid via ACH debit. |
ccEmails | array | Required within parent | Emails to be CCed on invoice notifications/reminders. |
ccEmails[] | string | Each item | |
creditCardEnabled | boolean | Required within parent | Whether or not the invoice can be paid via credit card. Requires Stripe to be setup for the Mercury account. |
currencyCode | JSON | Optional | |
currencyCode (anyOf 1) | JSON | Alternative | |
currencyCode (anyOf 1) (allOf 1) | string | All variants apply | |
currencyCode (anyOf 1) (allOf 2) | JSON | All variants apply | ISO 4217 currency code for the invoice. Defaults to USD if not provided. |
currencyCode (anyOf 2) | null | Alternative | |
customerId | JSON | Required within parent | |
customerId (allOf 1) | string | All variants apply | The customer who will receive the invoice. Use the /api/v1/ar/customers endpoint to list your customers and find the corresponding id, or create a new customer first. Format: uuid |
customerId (allOf 2) | JSON | All variants apply | Id of the customer the invoice was sent to. |
destinationAccountId | JSON | Required within parent | |
destinationAccountId (allOf 1) | string | All variants apply | ID for a Mercury account. Format: uuid |
destinationAccountId (allOf 2) | JSON | All variants apply | The Mercury account where invoice payments will be deposited. Use the /api/v1/accounts endpoint to list your accounts and find the corresponding id. Only checking and savings accounts are supported. |
dueDate | JSON | Required within parent | |
dueDate (allOf 1) | string | All variants apply | Format: date |
dueDate (allOf 2) | JSON | All variants apply | The due date the invoice should be paid by. YYYY-MM-DD |
internalNote | JSON | Optional | |
internalNote (anyOf 1) | string | Alternative | Internal note for the invoice, visible by users in the organization but not visible to payers. Maximum length: 5000 Minimum length: 1 |
internalNote (anyOf 2) | null | Alternative | |
invoiceDate | JSON | Required within parent | |
invoiceDate (allOf 1) | string | All variants apply | Format: date |
invoiceDate (allOf 2) | JSON | All variants apply | The date of the invoice, set by the invoice creator and likely to be context specific to the type of transaction. For example, it could be a date a service was performed. YYYY-MM-DD |
invoiceNumber | JSON | Optional | |
invoiceNumber (anyOf 1) | string | Alternative | The payer facing invoice number/identifier. Maximum length: 299 Minimum length: 1 |
invoiceNumber (anyOf 2) | null | Alternative | |
lineItems | array | Required within parent | The line items for the invoice |
lineItems[] | Model | Each item | Expand Create an invoice — request body — body line Items item |
payerMemo | JSON | Optional | |
payerMemo (anyOf 1) | string | Alternative | Memo for the payer of the invoice. Maximum length: 5000 Minimum length: 1 |
payerMemo (anyOf 2) | null | Alternative | |
poNumber | JSON | Optional | |
poNumber (anyOf 1) | string | Alternative | Purchase order number for the invoice, if applicable. Maximum length: 299 Minimum length: 1 |
poNumber (anyOf 2) | null | Alternative | |
sendEmailOption | JSON | Optional | |
sendEmailOption (anyOf 1) | JSON | Alternative | |
sendEmailOption (anyOf 1) (allOf 1) | string | All variants apply | One of: DontSend, SendNow |
sendEmailOption (anyOf 1) (allOf 2) | JSON | All variants apply | Rules for emailing the new invoice to payers. Can be "DontSend" to skip sending or "SendNow" to send immediately. If omitted, defaults to sending immediately. |
sendEmailOption (anyOf 2) | null | Alternative | |
servicePeriodEndDate | JSON | Optional | |
servicePeriodEndDate (anyOf 1) | JSON | Alternative | |
servicePeriodEndDate (anyOf 1) (allOf 1) | string | All variants apply | Format: date |
servicePeriodEndDate (anyOf 1) (allOf 2) | JSON | All variants apply | The end date for the service period this invoice covers, if applicable. YYYY-MM-DD |
servicePeriodEndDate (anyOf 2) | null | Alternative | |
servicePeriodStartDate | JSON | Optional | |
servicePeriodStartDate (anyOf 1) | JSON | Alternative | |
servicePeriodStartDate (anyOf 1) (allOf 1) | string | All variants apply | Format: date |
servicePeriodStartDate (anyOf 1) (allOf 2) | JSON | All variants apply | The start date for the service period this invoice covers, if applicable. YYYY-MM-DD |
servicePeriodStartDate (anyOf 2) | null | Alternative | |
useRealAccountNumber | boolean | Required within parent | Whether or not the invoice payment instructions will show the real account and routing number for the destination account or use virtual account numbers instead. Virtual accounts are safer and are preferred in most cases. |
Referenced models: Create an invoice — request body — body line Items item
Create an invoice — request body — body line Items item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Data for an invoice line item Additional keys: not allowed |
name | string | Required within parent | the name of the line item Maximum length: 299 Minimum length: 1 |
quantity | number | Required within parent | the quantity of this item Format: double |
salesTaxRate | JSON | Optional | |
salesTaxRate (anyOf 1) | number | Alternative | the sales tax applied to this item Format: double |
salesTaxRate (anyOf 2) | null | Alternative | |
unitPrice | number | Required within parent | the price of one unit of the item before sales tax Multiple of: 0.01 |
Get an attachment — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | The object representing a file attachment for an invoice. The file is not a part of this object itself but information for where to download it will be in this object. |
fileName | string | Required within parent | The filename for the file. Maximum length: 299 Minimum length: 1 |
id | JSON | Required within parent | |
id (allOf 1) | string | All variants apply | ID for the attachment. Format: uuid |
id (allOf 2) | JSON | All variants apply | The ID of the attachment object. |
url | string | Required within parent | The signed download URL for the file itself. |
Get an invoice — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | The response type for an invoice in the api. |
achDebitEnabled | boolean | Required within parent | Whether or not the invoice can be paid via ach debit. |
amount | JSON | Required within parent | |
amount (anyOf 1) | number | Alternative | The total amount of the invoice line items plus taxes. Multiple of: 0.01 |
amount (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
canceledAt | JSON | Optional | |
canceledAt (anyOf 1) | JSON | Alternative | |
canceledAt (anyOf 1) (allOf 1) | string | All variants apply | Format: yyyy-mm-ddThh:MM:ssZ |
canceledAt (anyOf 1) (allOf 2) | JSON | All variants apply | The time when the invoice was canceled. |
canceledAt (anyOf 2) | null | Alternative | |
ccEmails | array | Required within parent | Emails to be CCed on invoice notifications/reminders. |
ccEmails[] | string | Each item | |
createdAt | JSON | Required within parent | |
createdAt (allOf 1) | string | All variants apply | Format: yyyy-mm-ddThh:MM:ssZ |
createdAt (allOf 2) | JSON | All variants apply | The timestamp when the invoice was created. |
creditCardEnabled | boolean | Required within parent | Whether or not the invoice can be paid via credit card. Requires stripe to be setup for the Mercury account. |
currencyCode | JSON | Required within parent | |
currencyCode (allOf 1) | string | All variants apply | |
currencyCode (allOf 2) | JSON | All variants apply | ISO 4217 currency code for the invoice (e.g. "USD", "EUR"). |
customerId | JSON | Required within parent | |
customerId (allOf 1) | string | All variants apply | The customer who will receive the invoice. Use the /api/v1/ar/customers endpoint to list your customers and find the corresponding id, or create a new customer first. Format: uuid |
customerId (allOf 2) | JSON | All variants apply | Id of the customer the invoice was sent to. |
destinationAccountId | JSON | Required within parent | |
destinationAccountId (allOf 1) | string | All variants apply | ID for a Mercury account. Format: uuid |
destinationAccountId (allOf 2) | JSON | All variants apply | The Mercury account where invoice payments will be deposited. Use the /api/v1/accounts endpoint to list your accounts and find the corresponding id. Only checking and savings accounts are supported. |
dueDate | JSON | Required within parent | |
dueDate (allOf 1) | string | All variants apply | Format: date |
dueDate (allOf 2) | JSON | All variants apply | The due date the invoice should be paid by. |
id | JSON | Required within parent | |
id (allOf 1) | string | All variants apply | ID for the invoice. Format: uuid |
id (allOf 2) | JSON | All variants apply | The ID of the invoice. |
internalNote | JSON | Optional | |
internalNote (anyOf 1) | string | Alternative | Internal note for the invoice, visible by users in the mercury organization but not visible to payers. Maximum length: 5000 Minimum length: 1 |
internalNote (anyOf 2) | null | Alternative | |
invoiceDate | JSON | Required within parent | |
invoiceDate (allOf 1) | string | All variants apply | Format: date |
invoiceDate (allOf 2) | JSON | All variants apply | The date of the invoice, set by the invoice creator and likely to be context specific to the type of transaction. i.e. it could be a date a service was performed, it does not need to be the date the invoice was created. |
invoiceNumber | string | Required within parent | The payer facing invoice number/identifier. Maximum length: 299 Minimum length: 1 |
lineItems | array | Required within parent | The line items for the invoice. |
lineItems[] | Model | Each item | Expand Get an invoice — response body — line Items item |
payerMemo | JSON | Optional | |
payerMemo (anyOf 1) | string | Alternative | Memo for the payer of the invoice. Maximum length: 5000 Minimum length: 1 |
payerMemo (anyOf 2) | null | Alternative | |
poNumber | JSON | Optional | |
poNumber (anyOf 1) | string | Alternative | Purchase order number for the invoice if applicable. Maximum length: 299 Minimum length: 1 |
poNumber (anyOf 2) | null | Alternative | |
servicePeriodEndDate | JSON | Optional | |
servicePeriodEndDate (anyOf 1) | JSON | Alternative | |
servicePeriodEndDate (anyOf 1) (allOf 1) | string | All variants apply | Format: date |
servicePeriodEndDate (anyOf 1) (allOf 2) | JSON | All variants apply | The end date for the service period this invoice covers, if applicable. YYYY-MM-DD |
servicePeriodEndDate (anyOf 2) | null | Alternative | |
servicePeriodStartDate | JSON | Optional | |
servicePeriodStartDate (anyOf 1) | JSON | Alternative | |
servicePeriodStartDate (anyOf 1) (allOf 1) | string | All variants apply | Format: date |
servicePeriodStartDate (anyOf 1) (allOf 2) | JSON | All variants apply | The start date for the service period this invoice covers, if applicable. YYYY-MM-DD |
servicePeriodStartDate (anyOf 2) | null | Alternative | |
slug | string | Required within parent | Public slug for an invoice. Used to construct the pay page URL as well as the URL to retrieve the PDF of the invoice. |
status | JSON | Required within parent | |
status (allOf 1) | string | All variants apply | Known values: Unpaid, Paid, Cancelled, Processing |
status (allOf 2) | JSON | All variants apply | The status of the invoice. |
updatedAt | JSON | Required within parent | |
updatedAt (allOf 1) | string | All variants apply | Format: yyyy-mm-ddThh:MM:ssZ |
updatedAt (allOf 2) | JSON | All variants apply | The timestamp when the invoice was updated. |
useRealAccountNumber | boolean | Required within parent | Whether or not the invoice payment instructions will show the real account and routing number for the destination account or use virtual account numbers instead. |
Referenced models: Get an invoice — response body — line Items item
Get an invoice — response body — line Items item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Data for an invoice line item |
name | string | Required within parent | the name of the line item Maximum length: 299 Minimum length: 1 |
quantity | JSON | Required within parent | |
quantity (anyOf 1) | number | Alternative | the quantity of this item Format: double |
quantity (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
salesTaxRate | JSON | Optional | |
salesTaxRate (anyOf 1) | JSON | Alternative | |
salesTaxRate (anyOf 1) (anyOf 1) | number | Alternative | the sales tax applied to this item Format: double |
salesTaxRate (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
salesTaxRate (anyOf 2) | null | Alternative | |
unitPrice | JSON | Required within parent | |
unitPrice (anyOf 1) | number | Alternative | the price of one unit of the item before sales tax Multiple of: 0.01 |
unitPrice (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
List all invoices — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Paginated response containing a list of invoices. | Use the page cursor information to fetch additional pages of invoices. |
invoices | array | Required within parent | List of invoices in the current page |
invoices[] | Model | Each item | Expand List all invoices — response body — invoices item |
page | object | Required within parent | Pagination information including cursors for navigating to next/previous pages |
page.nextPage | string | Optional | ID for the invoice. Format: uuid |
page.previousPage | string | Optional | ID for the invoice. Format: uuid |
Referenced models: List all invoices — response body — invoices item
List all invoices — response body — invoices item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Response data for Accounts Receivable invoices API Endpoint |
achDebitEnabled | boolean | Required within parent | Whether or not the invoice can be paid via ach debit. |
amount | JSON | Required within parent | |
amount (anyOf 1) | number | Alternative | The total amount of the invoice line items plus taxes Multiple of: 0.01 |
amount (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
canceledAt | JSON | Optional | |
canceledAt (anyOf 1) | JSON | Alternative | |
canceledAt (anyOf 1) (allOf 1) | string | All variants apply | Format: yyyy-mm-ddThh:MM:ssZ |
canceledAt (anyOf 1) (allOf 2) | JSON | All variants apply | The time when the invoice was canceled. |
canceledAt (anyOf 2) | null | Alternative | |
ccEmails | array | Required within parent | Emails to be CCed on invoice notifications/reminders. |
ccEmails[] | string | Each item | |
createdAt | JSON | Required within parent | |
createdAt (allOf 1) | string | All variants apply | Format: yyyy-mm-ddThh:MM:ssZ |
createdAt (allOf 2) | JSON | All variants apply | The timestamp when the invoice was created. |
creditCardEnabled | boolean | Required within parent | Whether or not the invoice can be paid via credit card. Requires stripe to be setup for the Mercury account. |
currencyCode | JSON | Required within parent | |
currencyCode (allOf 1) | string | All variants apply | |
currencyCode (allOf 2) | JSON | All variants apply | ISO 4217 currency code for the invoice (e.g. "USD", "EUR"). |
customerId | JSON | Required within parent | |
customerId (allOf 1) | string | All variants apply | The customer who will receive the invoice. Use the /api/v1/ar/customers endpoint to list your customers and find the corresponding id, or create a new customer first. Format: uuid |
customerId (allOf 2) | JSON | All variants apply | Id of the customer the invoice was sent to. |
destinationAccountId | JSON | Required within parent | |
destinationAccountId (allOf 1) | string | All variants apply | ID for a Mercury account. Format: uuid |
destinationAccountId (allOf 2) | JSON | All variants apply | The Mercury account where invoice payments will be deposited. Use the /api/v1/accounts endpoint to list your accounts and find the corresponding id. Only checking and savings accounts are supported. |
dueDate | JSON | Required within parent | |
dueDate (allOf 1) | string | All variants apply | Format: date |
dueDate (allOf 2) | JSON | All variants apply | The due date the invoice should be paid by. |
id | JSON | Required within parent | |
id (allOf 1) | string | All variants apply | ID for the invoice. Format: uuid |
id (allOf 2) | JSON | All variants apply | The ID of the invoice. |
internalNote | JSON | Optional | |
internalNote (anyOf 1) | string | Alternative | Internal note for the invoice, visible by users in the mercury organization but not visible to payers. Maximum length: 5000 Minimum length: 1 |
internalNote (anyOf 2) | null | Alternative | |
invoiceDate | JSON | Required within parent | |
invoiceDate (allOf 1) | string | All variants apply | Format: date |
invoiceDate (allOf 2) | JSON | All variants apply | The date of the invoice, set by the invoice creator and likely to be context specific to the type of transaction. i.e. it could be a date a service was performed, it does not need to be the date the invoice was created. |
invoiceNumber | string | Required within parent | The payer facing invoice number/identifier. Maximum length: 299 Minimum length: 1 |
payerMemo | JSON | Optional | |
payerMemo (anyOf 1) | string | Alternative | Memo for the payer of the invoice. Maximum length: 5000 Minimum length: 1 |
payerMemo (anyOf 2) | null | Alternative | |
poNumber | JSON | Optional | |
poNumber (anyOf 1) | string | Alternative | Purchase order number for the invoice if applicable. Maximum length: 299 Minimum length: 1 |
poNumber (anyOf 2) | null | Alternative | |
slug | string | Required within parent | A unique identifier used to build public URLs for this invoice. Use it to construct the payment page URL (https://app.mercury.com/pay/{slug}) or fetch the invoice PDF via /api/v1/ar/invoices/{slug}/pdf. |
status | JSON | Required within parent | |
status (allOf 1) | string | All variants apply | Known values: Unpaid, Paid, Cancelled, Processing |
status (allOf 2) | JSON | All variants apply | The status of the invoice. |
updatedAt | JSON | Required within parent | |
updatedAt (allOf 1) | string | All variants apply | Format: yyyy-mm-ddThh:MM:ssZ |
updatedAt (allOf 2) | JSON | All variants apply | The timestamp when the invoice was updated. |
useRealAccountNumber | boolean | Required within parent | Whether or not the invoice payment instructions will show the real account and routing number for the destination account or use virtual account numbers instead. |
List invoice attachments — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | The response type for fetching attachments related to an AR Invoice. |
attachments | array | Required within parent | The list of attachments |
attachments[] | Model | Each item | Expand Get an attachment — response body |
Referenced models: Get an attachment — response body
Update an invoice — request body — body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | The request body to update an invoice. Additional keys: not allowed |
achDebitEnabled | boolean | Required within parent | Whether or not the invoice can be paid via ACH debit. |
ccEmails | array | Required within parent | List of emails to be CCed on notifications/reminders. |
ccEmails[] | string | Each item | |
creditCardEnabled | boolean | Required within parent | Whether or not the invoice can be paid via credit card. Requires Stripe to be setup for the Mercury account. |
dueDate | JSON | Required within parent | |
dueDate (allOf 1) | string | All variants apply | Format: date |
dueDate (allOf 2) | JSON | All variants apply | The date the invoice should be paid by. YYYY-MM-DD |
internalNote | JSON | Optional | |
internalNote (anyOf 1) | string | Alternative | Internal note for the invoice, visible by users in the organization but not visible to payers. Maximum length: 5000 Minimum length: 1 |
internalNote (anyOf 2) | null | Alternative | |
invoiceDate | JSON | Required within parent | |
invoiceDate (allOf 1) | string | All variants apply | Format: date |
invoiceDate (allOf 2) | JSON | All variants apply | The date of the invoice, set by the invoice creator. Does not have to be the day the invoice was created. It can be business specific i.e. service/sale date. YYYY-MM-DD |
invoiceNumber | string | Required within parent | The invoice number. Maximum length: 299 Minimum length: 1 |
lineItems | array | Required within parent | The line items for the invoice |
lineItems[] | Model | Each item | Expand Create an invoice — request body — body line Items item |
payerMemo | JSON | Optional | |
payerMemo (anyOf 1) | string | Alternative | Memo for the payer of the invoice. Maximum length: 5000 Minimum length: 1 |
payerMemo (anyOf 2) | null | Alternative | |
poNumber | JSON | Optional | |
poNumber (anyOf 1) | string | Alternative | The purchase order number for the invoice if applicable. Maximum length: 299 Minimum length: 1 |
poNumber (anyOf 2) | null | Alternative | |
servicePeriodEndDate | JSON | Optional | |
servicePeriodEndDate (anyOf 1) | JSON | Alternative | |
servicePeriodEndDate (anyOf 1) (allOf 1) | string | All variants apply | Format: date |
servicePeriodEndDate (anyOf 1) (allOf 2) | JSON | All variants apply | The end date for the service period this invoice covers, if applicable. YYYY-MM-DD |
servicePeriodEndDate (anyOf 2) | null | Alternative | |
servicePeriodStartDate | JSON | Optional | |
servicePeriodStartDate (anyOf 1) | JSON | Alternative | |
servicePeriodStartDate (anyOf 1) (allOf 1) | string | All variants apply | Format: date |
servicePeriodStartDate (anyOf 1) (allOf 2) | JSON | All variants apply | The start date for the service period this invoice covers, if applicable. YYYY-MM-DD |
servicePeriodStartDate (anyOf 2) | null | Alternative | |
useRealAccountNumber | boolean | Required within parent | Whether or not the invoice payment instructions will show the real account and routing number for the destination account or use virtual account numbers instead. |
Referenced models: Create an invoice — request body — body line Items item