Modern Treasury Invoice API
The Invoice API from Modern Treasury — 2 operation(s) for invoice.
OpenAPI Specification
openapi: 3.0.1
info:
title: Modern Treasury AccountCapability Invoice API
version: v1
contact:
name: Modern Treasury Engineering Team
url: https://moderntreasury.com
description: The Modern Treasury REST API. Please see https://docs.moderntreasury.com for more details.
servers:
- url: http://localhost:3000
- url: https://app.moderntreasury.com
tags:
- name: Invoice
paths:
/api/invoices:
get:
summary: list invoices
tags:
- Invoice
operationId: listInvoices
security:
- basic_auth: []
parameters:
- name: after_cursor
in: query
schema:
type: string
nullable: true
required: false
- name: per_page
in: query
required: false
schema:
type: integer
- name: counterparty_id
in: query
schema:
type: string
required: false
- name: originating_account_id
in: query
schema:
type: string
required: false
- name: payment_order_id
in: query
schema:
type: string
required: false
- name: expected_payment_id
in: query
schema:
type: string
required: false
- name: status
in: query
schema:
type: string
enum:
- draft
- paid
- partially_paid
- payment_pending
- unpaid
- voided
required: false
- name: number
in: query
schema:
type: string
description: A unique record number assigned to each invoice that is issued.
required: false
- name: due_date_start
in: query
schema:
type: string
format: date
description: An inclusive lower bound for searching due_date
required: false
- name: due_date_end
in: query
schema:
type: string
format: date
description: An inclusive upper bound for searching due_date
required: false
- name: created_at_start
in: query
schema:
type: string
format: date-time
description: An inclusive lower bound for searching created_at
required: false
- name: created_at_end
in: query
schema:
type: string
format: date-time
description: An inclusive upper bound for searching created_at
required: false
- $ref: '#/components/parameters/metadata_query'
responses:
'200':
description: successful
headers:
X-After-Cursor:
schema:
type: string
nullable: true
required: false
description: The cursor for the next page. Including this in a call as `after_cursor` will return the next page.
X-Per-Page:
schema:
type: integer
nullable: true
description: The current `per_page`.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/invoice'
post:
summary: create invoice
tags:
- Invoice
operationId: createInvoice
security:
- basic_auth: []
parameters:
- name: Idempotency-Key
in: header
required: false
description: This key should be something unique, preferably something like an UUID.
schema:
type: string
responses:
'200':
description: successful
content:
application/json:
schema:
$ref: '#/components/schemas/invoice'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/invoice_create_request'
/api/invoices/{id}:
parameters:
- name: id
in: path
schema:
type: string
description: id
required: true
get:
summary: get invoice
tags:
- Invoice
operationId: getInvoice
security:
- basic_auth: []
responses:
'200':
description: successful
content:
application/json:
schema:
$ref: '#/components/schemas/invoice'
patch:
summary: update invoice
tags:
- Invoice
operationId: updateInvoice
security:
- basic_auth: []
parameters: []
responses:
'200':
description: successful
content:
application/json:
schema:
$ref: '#/components/schemas/invoice'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/invoice_update_request'
components:
schemas:
payment_order_subtype:
type: string
enum:
- 0C
- 0N
- 0S
- CCD
- CIE
- CTX
- IAT
- PPD
- TEL
- WEB
- au_becs
- bacs
- base
- chats
- dk_nets
- eft
- ethereum
- hu_ics
- masav
- mx_ccen
- neft
- nics
- nz_becs
- pl_elixir
- polygon
- ro_sent
- se_bankgirot
- sepa
- sg_giro
- sic
- sknbi
- solana
- zengin
nullable: true
description: An additional layer of classification for the type of payment order you are doing. This field is only used for `ach` payment orders currently. For `ach` payment orders, the `subtype` represents the SEC code. We currently support `CCD`, `PPD`, `IAT`, `CTX`, `WEB`, `CIE`, and `TEL`.
x-stainless-renameMap:
bacs_new_instruction: 0C
bacs_cancellation_instruction: 0N
bacs_conversion_instruction: 0S
reconciliation_rule_variable:
type: object
properties:
amount_upper_bound:
type: integer
description: The highest amount this expected payment may be equal to. Value in specified currency's smallest unit. e.g. $10 would be represented as 1000.
amount_lower_bound:
type: integer
description: The lowest amount this expected payment may be equal to. Value in specified currency's smallest unit. e.g. $10 would be represented as 1000.
direction:
type: string
enum:
- credit
- debit
description: One of credit or debit. When you are receiving money, use credit. When you are being charged, use debit.
internal_account_id:
type: string
format: uuid
description: The ID of the Internal Account for the expected payment
type:
type: string
nullable: true
enum:
- ach
- au_becs
- bacs
- book
- card
- chats
- check
- cross_border
- dk_nets
- eft
- gb_fps
- hu_ics
- interac
- masav
- mx_ccen
- neft
- nics
- nz_becs
- pl_elixir
- provxchange
- ro_sent
- rtp
- se_bankgirot
- sen
- sepa
- sg_giro
- sic
- signet
- sknbi
- stablecoin
- wire
- zengin
description: One of ach, au_becs, bacs, book, check, eft, interac, provxchange, rtp, sen, sepa, signet wire
currency:
$ref: '#/components/schemas/currency'
description: Must conform to ISO 4217. Defaults to the currency of the internal account
date_upper_bound:
type: string
format: date
nullable: true
description: The latest date the payment may come in. Format is yyyy-mm-dd
date_lower_bound:
type: string
format: date
nullable: true
description: The earliest date the payment may come in. Format is yyyy-mm-dd
counterparty_id:
type: string
format: uuid
nullable: true
description: The ID of the counterparty you expect for this payment
custom_identifiers:
type: object
description: A hash of custom identifiers for this payment
nullable: true
additionalProperties:
type: string
additionalProperties: false
minProperties: 10
required:
- amount_upper_bound
- amount_lower_bound
- direction
- internal_account_id
account_capability:
type: object
properties:
id:
type: string
format: uuid
object:
type: string
live_mode:
type: boolean
description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
discarded_at:
type: string
format: date-time
nullable: true
direction:
type: string
enum:
- credit
- debit
description: One of `debit` or `credit`. Indicates the direction of money movement this capability is responsible for.
_x-stainless-modelDefPath: $shared.transaction_direction
identifier:
type: string
nullable: true
description: A unique reference assigned by your bank for tracking and recognizing payment files. It is important this is formatted exactly how the bank assigned it.
payment_type:
type: string
enum:
- ach
- au_becs
- bacs
- book
- card
- chats
- check
- cross_border
- dk_nets
- eft
- gb_fps
- hu_ics
- interac
- masav
- mx_ccen
- neft
- nics
- nz_becs
- pl_elixir
- provxchange
- ro_sent
- rtp
- se_bankgirot
- sen
- sepa
- sg_giro
- sic
- signet
- sknbi
- stablecoin
- wire
- zengin
description: Indicates the the type of payment this capability is responsible for originating.
additionalProperties: true
minProperties: 9
maxProperties: 9
required:
- id
- object
- live_mode
- created_at
- updated_at
- discarded_at
- direction
- identifier
- payment_type
currency:
type: string
enum:
- AED
- AFN
- ALL
- AMD
- ANG
- AOA
- ARS
- AUD
- AWG
- AZN
- BAM
- BBD
- BCH
- BDT
- BGN
- BHD
- BIF
- BMD
- BND
- BOB
- BRL
- BSD
- BTC
- BTN
- BWP
- BYN
- BYR
- BZD
- CAD
- CDF
- CHF
- CLF
- CLP
- CNH
- CNY
- COP
- CRC
- CUC
- CUP
- CVE
- CZK
- DJF
- DKK
- DOP
- DZD
- EEK
- EGP
- ERN
- ETB
- ETH
- EUR
- EURC
- FJD
- FKP
- GBP
- GBX
- GEL
- GGP
- GHS
- GIP
- GMD
- GNF
- GTQ
- GYD
- HKD
- HNL
- HRK
- HTG
- HUF
- IDR
- ILS
- IMP
- INR
- IQD
- IRR
- ISK
- JEP
- JMD
- JOD
- JPY
- KES
- KGS
- KHR
- KMF
- KPW
- KRW
- KWD
- KYD
- KZT
- LAK
- LBP
- LKR
- LRD
- LSL
- LTL
- LVL
- LYD
- MAD
- MDL
- MGA
- MKD
- MMK
- MNT
- MOP
- MRO
- MRU
- MTL
- MUR
- MVR
- MWK
- MXN
- MYR
- MZN
- NAD
- NGN
- NIO
- NOK
- NPR
- NZD
- OMR
- OP
- PAB
- PEN
- PGK
- PHP
- PKR
- PLN
- PYG
- PYUSD
- QAR
- RON
- RSD
- RUB
- RWF
- SAR
- SBD
- SCR
- SDG
- SEK
- SGD
- SHP
- SKK
- SLE
- SLL
- SOS
- SRD
- SSP
- STD
- STN
- SVC
- SYP
- SZL
- THB
- TJS
- TMM
- TMT
- TND
- TOP
- TRY
- TTD
- TWD
- TZS
- UAH
- UGX
- USD
- USDB
- USDC
- USDG
- USDP
- USDT
- UYU
- UZS
- VEF
- VES
- VND
- VUV
- WST
- XAF
- XAG
- XAU
- XBA
- XBB
- XBC
- XBD
- XCD
- XCG
- XDR
- XFU
- XOF
- XPD
- XPF
- XPT
- XTS
- YER
- ZAR
- ZMK
- ZMW
- ZWD
- ZWG
- ZWL
- ZWN
- ZWR
description: Three-letter ISO currency code.
routing_detail:
type: object
properties:
id:
type: string
format: uuid
object:
type: string
live_mode:
type: boolean
description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
discarded_at:
type: string
format: date-time
nullable: true
routing_number:
type: string
description: The routing number of the bank.
routing_number_type:
type: string
enum:
- aba
- au_bsb
- br_codigo
- ca_cpa
- chips
- cnaps
- dk_interbank_clearing_code
- gb_sort_code
- hk_interbank_clearing_code
- hu_interbank_clearing_code
- id_sknbi_code
- il_bank_code
- in_ifsc
- jp_zengin_code
- mx_bank_identifier
- my_branch_code
- nz_national_clearing_code
- pl_national_clearing_code
- se_bankgiro_clearing_code
- sg_interbank_clearing_code
- swift
- za_national_clearing_code
description: The type of routing number. See https://docs.moderntreasury.com/platform/reference/routing-detail-object for more details.
payment_type:
type: string
enum:
- ach
- au_becs
- bacs
- book
- card
- chats
- check
- cross_border
- dk_nets
- eft
- gb_fps
- hu_ics
- interac
- masav
- mx_ccen
- neft
- nics
- nz_becs
- pl_elixir
- provxchange
- ro_sent
- rtp
- se_bankgirot
- sen
- sepa
- sg_giro
- sic
- signet
- sknbi
- stablecoin
- wire
- zengin
nullable: true
description: If the routing detail is to be used for a specific payment type this field will be populated, otherwise null.
bank_name:
type: string
description: The name of the bank.
bank_address:
$ref: '#/components/schemas/address'
additionalProperties: false
minProperties: 11
required:
- id
- object
- live_mode
- created_at
- updated_at
- discarded_at
- routing_number
- routing_number_type
- payment_type
- bank_name
- bank_address
invoice_create_request:
type: object
properties:
contact_details:
type: array
items:
$ref: '#/components/schemas/contact_detail'
description: The invoicer's contact details displayed at the top of the invoice.
recipient_email:
type: string
nullable: true
description: The email of the recipient of the invoice. Leaving this value as null will fallback to using the counterparty's name.
recipient_name:
type: string
nullable: true
description: The name of the recipient of the invoice. Leaving this value as null will fallback to using the counterparty's name.
counterparty_id:
type: string
description: The ID of the counterparty receiving the invoice.
counterparty_billing_address:
type: object
nullable: true
description: The counterparty's billing address.
properties:
line1:
type: string
line2:
type: string
locality:
type: string
description: Locality or City.
region:
type: string
description: Region or State.
postal_code:
type: string
description: The postal code of the address.
country:
type: string
description: Country code conforms to [ISO 3166-1 alpha-2]
required:
- line1
- locality
- region
- postal_code
- country
counterparty_shipping_address:
type: object
nullable: true
description: The counterparty's shipping address where physical goods should be delivered.
properties:
line1:
type: string
line2:
type: string
locality:
type: string
description: Locality or City.
region:
type: string
description: Region or State.
postal_code:
type: string
description: The postal code of the address.
country:
type: string
description: Country code conforms to [ISO 3166-1 alpha-2]
required:
- line1
- locality
- region
- postal_code
- country
currency:
$ref: '#/components/schemas/currency'
description: Currency that the invoice is denominated in. Defaults to `USD` if not provided.
description:
type: string
description: A free-form description of the invoice.
due_date:
type: string
format: date-time
description: A future date by when the invoice needs to be paid.
invoicer_name:
type: string
nullable: true
description: The name of the issuer for the invoice. Defaults to the name of the Organization.
invoicer_address:
type: object
nullable: true
description: The invoice issuer's business address.
properties:
line1:
type: string
line2:
type: string
locality:
type: string
description: Locality or City.
region:
type: string
description: Region or State.
postal_code:
type: string
description: The postal code of the address.
country:
type: string
description: Country code conforms to [ISO 3166-1 alpha-2]
required:
- line1
- locality
- region
- postal_code
- country
originating_account_id:
type: string
description: The ID of the internal account the invoice should be paid to.
receiving_account_id:
type: string
format: uuid
description: The receiving account ID. Can be an `external_account`.
virtual_account_id:
type: string
format: uuid
nullable: true
description: The ID of the virtual account the invoice should be paid to.
payment_effective_date:
type: string
format: date
description: 'Date transactions are to be posted to the participants'' account. Defaults to the current business day or the next business day if the current day is a bank holiday or weekend. Format: yyyy-mm-dd.'
payment_type:
$ref: '#/components/schemas/payment_order_type'
payment_method:
type: string
enum:
- ui
- manual
- automatic
description: The method by which the invoice can be paid. `ui` will show the embedded payment collection flow. `automatic` will automatically initiate payment based upon the account details of the receiving_account id.\nIf the invoice amount is positive, the automatically initiated payment order's direction will be debit. If the invoice amount is negative, the automatically initiated payment order's direction will be credit. One of `manual`, `ui`, or `automatic`.
fallback_payment_method:
type: string
nullable: true
description: When payment_method is automatic, the fallback payment method to use when an automatic payment fails. One of `manual` or `ui`.
notifications_enabled:
type: boolean
description: If true, the invoice will send email notifications to the invoice recipients about invoice status changes.
notification_email_addresses:
type: array
nullable: true
items:
type: string
description: Emails in addition to the counterparty email to send invoice status notifications to. At least one email is required if notifications are enabled and the counterparty doesn't have an email.
remind_after_overdue_days:
type: array
nullable: true
items:
type: integer
description: Number of days after due date when overdue reminder emails will be sent out to invoice recipients.
invoice_line_items:
type: array
nullable: true
items:
$ref: '#/components/schemas/invoice_line_item_create_request'
description: An array of invoice line items. The API supports a maximum of 50 invoice line items per invoice. If a greater number of invoice line items is required, please contact support.
auto_advance:
type: boolean
nullable: true
description: When true, the invoice will progress to unpaid automatically and cannot be edited after entering that state. If the invoice fails to progress to unpaid, the errors will be returned and the invoice will not be created.
metadata:
type: object
description: Additional data represented as key-value pairs. Both the key and value must be strings.
additionalProperties:
type: string
example:
key: value
foo: bar
modern: treasury
nullable: true
required:
- counterparty_id
- due_date
- originating_account_id
address:
type: object
properties:
id:
type: string
format: uuid
object:
type: string
live_mode:
type: boolean
description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
line1:
type: string
nullable: true
line2:
type: string
nullable: true
locality:
type: string
nullable: true
description: Locality or City.
region:
type: string
nullable: true
description: Region or State.
postal_code:
type: string
description: The postal code of the address.
nullable: true
country:
type: string
description: Country code conforms to [ISO 3166-1 alpha-2]
nullable: true
nullable: true
additionalProperties: false
minProperties: 11
required:
- id
- object
- live_mode
- created_at
- updated_at
- line1
- line2
- locality
- region
- postal_code
- country
account_detail:
type: object
properties:
id:
type: string
format: uuid
object:
type: string
live_mode:
type: boolean
description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
discarded_at:
type: string
format: date-time
nullable: true
account_number:
type: string
description: The account number for the bank account.
account_number_type:
type: string
enum:
- au_number
- base_address
- card_token
- clabe
- ethereum_address
- hk_number
- iban
- id_number
- nz_number
- other
- pan
- polygon_address
- sg_number
- solana_address
- wallet_address
description: One of `iban`, `clabe`, `wallet_address`, or `other`. Use `other` if the bank account number is in a generic format.
account_number_safe:
type: string
description: The last 4 digits of the account_number.
additionalProperties: false
minProperties: 8
maxProperties: 9
required:
- id
- object
- live_mode
- created_at
- updated_at
- discarded_at
- account_number_type
- account_number_safe
internal_account:
type: object
properties:
id:
type: string
format: uuid
object:
type: string
live_mode:
type: boolean
description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
account_type:
type: string
enum:
- base_wallet
- cash
- checking
- crypto_wallet
- ethereum_wallet
- general_ledger
- loan
- non_resident
- other
- overdraft
- polygon_wallet
- savings
- solana_wallet
nullable: true
description: Can be checking, savings or other.
party_name:
type: string
description: The legal name of the entity which owns the account.
party_type:
type: string
enum:
- business
- individual
nullable: true
description: Either individual or business.
party_address:
$ref: '#/components/schemas/address'
description: The address associated with the owner or null.
name:
type: string
nullable: true
description: A nickname for the account.
account_details:
type: array
items:
$ref: '#/components/schemas/account_detail'
description: An array of account detail objects.
account_capabilities:
type: array
description: An array of AccountCapability objects that list the originating abilities of the internal account and any relevant information for them.
items:
$ref: '#/components/schemas/account_capability'
routing_details:
type: array
items:
$ref: '#/components/schemas/routing_detail'
description: An array of routing detail objects.
connection:
$ref: '#/components/schemas/connection'
description: Specifies which financial institution the accounts belong to.
currency:
$ref: '#/components/schemas/currency'
description: The currency of the account.
metadata:
type: object
additionalProperties:
type: string
example:
key: value
foo: bar
modern: treasury
description: Additional data represented as key-value pairs. Both the key and value must be strings.
parent_account_id:
type: string
format: uuid
nullable: true
description: The parent InternalAccount of this account.
counterparty_id:
type: string
format: uuid
nullable: true
description: The Counterparty associated to this account.
vendor_id:
type: string
format: string
nullable: true
description: The vendor ID associated with this account.
legal_entity_id:
type: string
format: uuid
nullable: true
description: The Legal Entity associated to this account.
status:
type: string
format: string
nullable: true
enum:
- active
- closed
- pending_activation
- pending_closure
- suspended
description: The internal account status.
ledger_account_id:
type: string
format: uuid
nullable: true
description: If the internal account links to a ledger account in Modern Treasury, the id of the ledger account will be populated here.
contra_ledger_account_id:
type: string
format: uuid
nullable: true
description: If the internal account links to a contra ledger account in Modern Treasury, the id of the contra ledger account will be populated here.
external_id:
type: string
nullable: true
description: An optional user-defined 180 character unique identifier.
additionalProperties: false
minProperties: 24
required:
- id
- object
- live_mode
- created_at
- updated_at
- account_type
- party_name
- party_type
- party_address
- name
- account_details
- account_capabilities
- routing_details
- connection
- currency
- metadata
- parent_account_id
- counterparty_id
- vendor_id
- legal_entity_id
- status
- ledger_account_id
- contra_ledger_account_id
- external_id
payment_order_type:
type: string
enum:
- ach
- au_becs
- bacs
- book
- card
- chats
- check
- cross_border
- dk_nets
- eft
- gb_fps
- hu_ics
- interac
- masav
- mx_ccen
- neft
- nics
- nz_becs
- pl_elixir
- provxchange
- ro_sent
- rtp
- se_bankgirot
- sen
- sepa
- sg_giro
- sic
- signet
- sknbi
- stablecoin
- wire
- zengin
description: One of `ach`, `se_bankgirot`, `eft`, `wire`, `check`, `sen`, `book`, `rtp`, `sepa`, `bacs`, `au_becs`, `interac`, `neft`, `nics`, `nz_national_clearing_code`, `sic`, `signet`, `provexchange`, `zengin`.
invoice:
type: object
properties:
id:
type: string
format: uuid
object:
type: string
live_mode:
type: boolean
description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
contact_details:
type: array
items:
$ref: '#/components/schemas/contact_detail'
description: The invoicer's contact details displayed at the top of
# --- truncated at 32 KB (91 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/modern-treasury/refs/heads/main/openapi/modern-treasury-invoice-api-openapi.yml