Create an invoice
How to create an invoice
Prerequisites
Before you create an invoice, you will need some information handy.
Get your Organization ID and API Key
Log into the app and go to your API Keys page. There you will find your organization ID and API keys.
Create or get your Counterparty
Before you can create an invoice, you need to have a counterparty in Modern Treasury.
You can get an existing counterparty's ID from your counterparties page here. If you do not have the counterparty in Modern Treasury, you can create a counterparty either via the web app or the API.
Here is an example API request to create a counterparty:
curl --request POST \
-u ORGANIZATION_ID:API_KEY \
--url https://app.moderntreasury.com/api/counterparties \
--header 'content-type: application/json' \
--data '{
"name": "Jane Smith",
"email": "jane@marquardtschuppe.net"
}'
Once the counterparty is successfully created, save the counterparty ID from the response body, which in this case is 342b0006-97b9-4b59-bd3d-5dfb220ff18b
:
{
"id": "342b0006-97b9-4b59-bd3d-5dfb220ff18b",
"object": "counterparty",
"live_mode": true,
"name": "Jane Smith",
"email": "jane@marquardtschuppe.net",
"send_remittance_advice": false,
"metadata": {},
"accounts": [],
"discarded_at": null,
"created_at": "2023-04-13T16:14:41Z",
"updated_at": "2023-04-13T16:14:41Z"
}
For more details, see our API reference for counterparties.
Get your Originating Account ID
When you send a counterparty an invoice, you must designate one of your internal accounts as the account that money will deposited into when the invoice is paid. If the invoice is paid via ACH debit, then the internal account will originate an ACH debit against the counterparty's bank account.
To get an internal account ID, you can pick one from your accounts page here.
Create an Invoice
Next, you will create an invoice using our API. You must include the following fields:
- Invoice counterparty ID
- Originating account ID
- Due date
You can only set the invoice's contact details (your email, phone number, and website) when creating the invoice; you will not be able to update these. When creating an invoice, you are able to create invoice line items in the same request.
If you set auto_advance
to true, the invoice will automatically be marked as ready-to-collect and will automatically progress the invoice to the status unpaid
. An invoice in the unpaid
status cannot be modified afterwards.
If you set payment_method
to automatic, the receiving_account_id
, payment_effective_date
, and payment_type
fields must be set.
See our invoice API reference docs for more invoice fields that you can set.
curl --request POST \
-u 'ORGANIZATION_ID:API_KEY' \
--url https://app.moderntreasury.com/api/invoices \
--header 'content-type: application/json' \
--data '{
"auto_advance": false,
"currency": "USD",
"counterparty_id": "342b0006-97b9-4b59-bd3d-5dfb220ff18b",
"originating_account_id": "0f8e3719-3dfd-4613-9bbf-c0333781b59f",
"due_date": "2023-04-30T20:36:28Z",
"contact_details": [
{
"contact_identifier": "my-email@example.com",
"contact_identifier_type": "email"
},
{
"contact_identifier": "example.com",
"contact_identifier_type": "website"
}
],
"invoice_line_items": [
{
"name": "implementation fee",
"description": "Fee for August 2023",
"direction": "debit",
"quantity": 1,
"unit_amount": 2050
}
],
}'
The response will look like the following:
{
"id": "4470104e-0921-4054-a0bc-98531262ea83",
"object": "invoice",
"live_mode": true,
"currency": "USD",
"description": null,
"total_amount": 0,
"number": "2023-00013",
"status": "draft",
"counterparty_id": "342b0006-97b9-4b59-bd3d-5dfb220ff18b",
"originating_account_id": "0f8e3719-3dfd-4613-9bbf-c0333781b59f",
"due_date": "2023-04-30T20:36:28Z",
"hosted_url": "https://payments.moderntreasury.com/invoices/4470104e-0921-4054-a0bc-98531262ea8?organization_id=61ef5b0-bb58-4113-a162-b5e3d5952fc7",
"pdf_url": null,
"contact_details": [
{
"contact_identifier": "my-email@example.com",
"contact_identifier_type": "email"
},
{
"contact_identifier": "example.com",
"contact_identifier_type": "website"
},
],
"invoicer_address": null,
"counterparty_billing_address": null,
"counterparty_shipping_address": null,
"payment_orders": [],
"created_at": "2023-03-27T20:36:28Z",
"updated_at": "2023-03-27T20:36:28Z"
}
You can view the invoice at the hosted URL in the response body.
(Optional) Adding your company logo to invoices
The invoice will include your company logo automatically. To change or add a logo for your organization, navigate to your organization's settings page and click the Logo tab.
(Optional) Attaching a ledger account settlement to an invoice
An ledger account settlement may be attached to an invoice to automatically update the ledger account settlement's status as the invoice status changes. This connection is explained further in Link a ledger account settlement to an invoice
Updated 12 months ago