Invoices beta
Invoices are built directly into Moov's platform, so you can send professional, branded invoices to your customers and accept payments without relying on third‑party tools. With invoicing you can:
- Create detailed line items
- Automatically generate secure payment links
- Send directly to customers via email
- Accept one-time payments via bank transfer or card
- Manually mark invoices as paid for off-platform payments
When using the invoice API, provide the customerAccountID in the request create an invoice. When a customer pays an invoice, funds are collected and deposited directly into the merchant's Moov wallet.
To create an invoice, use the POST create invoice endpoint. To send an invoice, use the PATCH update invoice endpoint and set the status to unpaid.
Invoice details
In addition to amount due, an invoice contains the following details:
| Component | Description |
|---|---|
| Invoice number | Automatically generated and sequential per account, for example, INV‑1001. |
| Invoice date | The date the service or sale occurred. This can differ from when the invoice is sent. |
| Due date | When the payment is due to the merchant. |
| Description | Optional notes shown to the customer, for example, job numbers or description of services provided. |
Line items
Each invoice includes one or more line items that describe what's being charged. Line items can be products from the account’s product catalog, or free-from line items that support custom names, prices, and quantities.
When you use a productID, Moov attaches the associated product image from your catalog to the line item. You must still specify the basePrice for the line item, as the price from the product catalog is not used. You can also use the productID for your own reporting and tracking.
Invoice status
An invoice can be in any of the following stages: draft, unpaid, payment-pending, paid, overdue, or canceled. When an invoice is created but not sent, it becomes a draft. While in draft status, all fields in the invoice can be edited. An invoice must be explicitly sent to trigger the payment link and email notification. Once the invoice is sent, it is marked as unpaid.
Upon successful payment, a receipt will be sent to the customer and the merchant will be notified of payment via email. Additionally, a webhook notification is sent.
A failed payment will result in the invoice being re-sent to the payer via the same payment link to retry. The original failed payment is logged and shown to the payer in the invoice and the merchant is notified of the failed payment via email.
If an invoice is not paid by the due date and becomes overdue, Moov will notify the merchant via email.
If an invoice is canceled, the payment link will be disabled and will throw an error if interacted with: This invoice has already been paid or is no longer valid.
Payment links & transfer status
When an invoice is sent, Moov automatically creates a secure payment link scoped to that invoice and customer. The payment link is a unique, single-use payment link which displays:
- Your business name and logo
- The invoice details
- Total amount due
A transfer is created for record keeping. The transferID can be found in invoicePayments.transfer within the create an invoice response. The table below shows the mapping of invoice status to payment link and transfer status.
| Invoice status | Payment link status | Transfer status |
|---|---|---|
draft |
N/A | N/A |
unpaid |
active |
N/A |
payment-pending |
disabled |
pending |
paid |
disabled |
completed |
overdue |
active |
N/A |
canceled |
disabled |
N/A |
Email notifications
Invoices are attached to an email in PDF format and are sent in a variety of scenarios. Moov sends an email to the payer when the invoice status is updated to one of the following:
- Unpaid
- Paid (receipt)
- Overdue
- Payment failed
- Canceled
Additionally, an email is sent if the transaction has been refunded.
Moov sends an email to the merchant when an invoice status is updated to paid, or if it's manually marked as paid. Moov also notifies merchants if the invoice is overdue, or the payment transaction is disputed.
If a logo has been added to the merchant's settings, the logo will be automatically added to the email. Below is an example of an email someone will receive for a payment request.
Create and manage invoices
Follow the steps below to create and manage invoices via the invoice API. Most of the endpoints in the invoice API will require you to pass the invoiceID which is returned in the create an invoice response.
Create invoice
Use the POST create invoice endpoint to create an invoice. You'll need to send the customerAccountID in the request body as well as create at least one line item.
curl -X POST "https://api.moov.io/accounts/{accountID}/invoices" \
-H "Authorization: Bearer {token}" \
--data '{
"customerAccountID": "d8b40343-5784-4096-8d40-9f3b4a834066",
"description": "string",
"lineItems": {
"items": [
{
"name": "string",
"basePrice": {
"currency": "USD",
"valueDecimal": "12.987654321"
},
"quantity": 1,
"options": [
{
"name": "string",
"quantity": 1,
"priceModifier": {
"currency": "USD",
"valueDecimal": "12.987654321"
},
"group": "string"
}
],
"productID": "dbb08e34-cbbb-47d7-824b-bc71f5b00e6c"
}
]
},
"dueDate": "2025-08-24T14:15:22Z",
"invoiceDate": "2025-08-24T14:15:22Z",
"taxAmount": {
"currency": "USD",
"valueDecimal": "12.987654321"
}
}'\
Optional: Update invoice
Use the PATCH update invoice endpoint to update an invoice's line items, tax amount, due date, invoice date, description, or status. Only invoices in the draft, unpaid or overdue status can be updated and the dueDate can only be updated if the invoice status is draft.
Note that setting an invoice's status to unpaid finalizes the invoice and sends an email with a payment link to the customer.
curl -X PATCH "https://api.moov.io/accounts/{accountID}/invoices/{invoiceID}" \
-H "Authorization: Bearer {token}" \
--data '{
"description": "string",
"lineItems": {
"items": [
{
"name": "string",
"basePrice": {
"currency": "USD",
"valueDecimal": "13.987654321"
},
"quantity": 2,
"options": [
{
"name": "string",
"quantity": 1,
"priceModifier": {
"currency": "USD",
"valueDecimal": "1.00"
},
"group": "string"
}
],
"productID": "dbb08e34-cbbb-47d7-824b-bc71f5b00e6c"
}
]
},
"dueDate": "2025-08-24T14:15:22Z",
"invoiceDate": "2025-08-24T14:15:22Z",
"status": "draft",
"taxAmount": {
"currency": "USD",
"valueDecimal": "12.987654321"
}
}'\
Send invoice
To send an invoice, you'll use the same PATCH update invoice endpoint as mentioned in the previous step. To send an invoice, set the status to unpaid. Setting an invoice's status to unpaid finalizes the invoice and sends an email with a payment link to the customer.
|
|
Get invoices
Use the invoiceID to view a specific invoice, or retrieve a list of all invoices.
Use the GET retrieve invoice endpoint and pass the invoiceID.
curl -X GET "https://api.moov.io/accounts/{accountID}/invoices/{invoiceID}" \
-H "Authorization: Bearer {token}" \
Use the GET list invoices endpoint.
curl -X GET "https://api.moov.io/accounts/{accountID}/invoices" \
-H "Authorization: Bearer {token}" \
Optional: Manually mark as paid
Create an external payment invoice resource and mark an invoice as paid outside of Moov's system with the payment resource endpoint.
curl -X POST "/accounts/{accountID}/invoices/{invoiceID}/payments" \
-H "Authorization: Bearer {token}" \
--data '{
"amount": {
"currency": "USD",
"valueDecimal": "12.987654321"
},
"description": "string",
"foreignID": "d8b40343-5784-4096-8d40-9f3b4a834066",
"paymentDate": "2025-08-24T14:15:22Z"
}'\
Note - invoices that are paid via payment link will be automatically marked as paid.
List payments
Pass the invoiceID to retrieve all payments made toward an invoice with the GET payments endpoint.
curl -X GET "/accounts/{accountID}/invoices/{invoiceID}/payments" \
-H "Authorization: Bearer {token}" \
Receive funds
Once the transfer completes, the invoice is marked as paid and the funds are available in the senders wallet.
Manually mark as paid
Invoices that are paid via payment link will be automatically marked as paid, however, you can manually mark an invoice as paid with the POST payment resource endpoint. Manually marking an invoice as paid notifies the merchant via email, sends a receipt to the customer, and cancels the corresponding payment link. Additionally, a webhook event is sent and a foreignID is added to the invoice.
You can only mark an invoice as paid if the status is unpaid or overdue.
curl -X POST "/accounts/{accountID}/invoices/{invoiceID}/payments" \
-H "Authorization: Bearer {token}" \
--data '{
"amount": {
"currency": "USD",
"valueDecimal": "12.987654321"
},
"description": "string",
"foreignID": "d8b40343-5784-4096-8d40-9f3b4a834066",
"paymentDate": "2025-08-24T14:15:22Z"
}'\
Payment failures & refunds
If a payment attempt fails, the invoice will automatically return to an unpaid status. The original payment link remains active, allowing the customer to retry the payment using the same link.
If a payment is refunded or disputed, the invoice will continue to show a paid status. Any refunded or disputed amounts are reflected directly on the invoice so you can see how much has been returned. Refunds and disputes follow Moov’s standard payment flow, meaning the refunded or disputed amount is deducted from the account’s wallet.
Webhooks
Subscribe to the following webhook events, which will provide you with relevant invoice updates:
invoice.creatednotifies you when an invoice was successfully createdinvoice.updatednotifies you when an invoice was updated