Skip to main content
Create and manage invoices programmatically.

​
Endpoints

MethodEndpointDescription
GET/invoicesList invoices
GET/invoices/:idGet invoice
POST/invoicesCreate invoice
PUT/invoices/:idUpdate invoice
POST/invoices/:id/sendSend invoice
POST/invoices/:id/voidVoid invoice

​
List Invoices

GET /mfi/invoices

​
Query Parameters

ParameterTypeDescription
pagenumberPage number (default: 1)
limitnumberItems per page (default: 20, max: 100)
statusstringFilter by status: draft, sent, viewed, paid, overdue, void
clientIdstringFilter by client ID
searchstringSearch invoice number or client name

​
Response

{
  "data": [
    {
      "id": "inv_xxxxxxxx",
      "invoiceNumber": "INV-001",
      "clientId": "cli_xxxxxxxx",
      "client": {
        "id": "cli_xxxxxxxx",
        "firstName": "Jean",
        "lastName": "Pierre"
      },
      "amount": "500.00",
      "currency": "HTG",
      "status": "sent",
      "dueDate": "2026-02-15",
      "createdAt": "2026-01-25T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 50,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}

​
Get Invoice

GET /mfi/invoices/:id

​
Response

{
  "id": "inv_xxxxxxxx",
  "invoiceNumber": "INV-001",
  "clientId": "cli_xxxxxxxx",
  "client": {
    "id": "cli_xxxxxxxx",
    "firstName": "Jean",
    "lastName": "Pierre",
    "email": "[email protected]"
  },
  "lineItems": [
    {
      "description": "Monthly Water Service",
      "quantity": 1,
      "unitPrice": "500.00",
      "amount": "500.00"
    }
  ],
  "subtotal": "500.00",
  "tax": "0.00",
  "total": "500.00",
  "currency": "HTG",
  "status": "sent",
  "dueDate": "2026-02-15",
  "memo": "January 2026 water bill",
  "paymentLink": {
    "url": "https://pay.bousol.app/pi/pi_xxxxx?t=token",
    "expiresAt": null
  },
  "createdAt": "2026-01-25T10:00:00Z",
  "sentAt": "2026-01-25T10:05:00Z",
  "paidAt": null
}

​
Create Invoice

POST /mfi/invoices

​
Request Body

{
  "clientId": "cli_xxxxxxxx",
  "currency": "HTG",
  "dueDate": "2026-02-15",
  "lineItems": [
    {
      "description": "Monthly Water Service",
      "quantity": 1,
      "unitPrice": 500.00
    }
  ],
  "memo": "January 2026 water bill"
}

​
Fields

FieldTypeRequiredDescription
clientIdstringYesClient ID
currencystringYesHTG or USD
dueDatestringYesDue date (YYYY-MM-DD)
lineItemsarrayYesAt least one line item
lineItems[].descriptionstringYesItem description
lineItems[].quantitynumberYesQuantity
lineItems[].unitPricenumberYesPrice per unit
memostringNoNote for customer
sendImmediatelybooleanNoSend after creation (default: false)

​
Response

Returns the created invoice (same format as Get Invoice).

​
Update Invoice

PUT /mfi/invoices/:id
Only draft invoices can be updated.

​
Request Body

{
  "dueDate": "2026-02-20",
  "lineItems": [
    {
      "description": "Monthly Water Service - Updated",
      "quantity": 1,
      "unitPrice": 550.00
    }
  ]
}

​
Send Invoice

POST /mfi/invoices/:id/send
Sends the invoice to the customer via email and/or SMS.

​
Request Body

{
  "channels": ["email", "sms"]
}

​
Fields

FieldTypeRequiredDescription
channelsarrayNoemail, sms, or both (default: both if available)

​
Response

{
  "success": true,
  "sentVia": ["email", "sms"],
  "status": "sent"
}

​
Void Invoice

POST /mfi/invoices/:id/void
Cancels an invoice. Cannot void paid invoices.

​
Request Body

{
  "reason": "Customer requested cancellation"
}

​
Response

{
  "success": true,
  "status": "void"
}

​
Errors

StatusCodeDescription
400invalid_clientClient ID not found
400invalid_line_itemsLine items validation failed
400cannot_updateInvoice not in draft status
400cannot_voidInvoice already paid
404not_foundInvoice not found

​
Webhooks

Subscribe to invoice events:
  • invoice.created
  • invoice.sent
  • invoice.viewed
  • invoice.paid
  • invoice.overdue
  • invoice.voided
See Webhooks for setup instructions.