Create Invoice

Generates a new invoice for a customer.

Authentication required (User JWT).

POST /api/merchants/:merchantId/invoices

Path Parameters

Parameter	Type	Description
merchantId	String	The ID of the parent merchant.

Request Body

{
  "customerEmail": "customer@example.com",
  "customerName": "Jane Doe", // Optional
  "customerNote": "Please reference PO #123.", // Optional note displayed to customer
  "lineItems": [
    {
      "description": "Web Development Service",
      "amount": 15000000, // 150,000 NGN in kobo
      "quantity": 1
    },
    {
      "description": "Hosting Fee (Monthly)",
      "amount": 500000, // 5,000 NGN in kobo
      "quantity": 1
    }
  ],
  "dueDate": "2023-11-30", // Optional: YYYY-MM-DD format
  "merchantNote": "Follow up if not paid by EOM.", // Optional: Internal note
  "status": "DRAFT" // Optional: Defaults to DRAFT. Can be SENT etc. if logic allows.
}

Field	Type	Required	Description
customerEmail	String	Yes	Email address of the customer receiving the invoice.
customerName	String	No	Customer's name.
customerNote	String	No	Note to display to the customer on the invoice.
lineItems	Array of LineItemDto objects	Yes	Array of items/services being invoiced. Must contain at least one.
lineItems[].description	String	Yes	Description of the line item.
lineItems[].amount	Integer	Yes	Price per unit in kobo/cents.
lineItems[].quantity	Number	Yes	Quantity of the item.
dueDate	String (YYYY-MM-DD)	No	Date the invoice payment is due.
merchantNote	String	No	Internal note for the merchant, not shown to the customer.
status	String (InvoiceStatus)	No	Initial status (e.g., DRAFT, SENT). Defaults to DRAFT.

Response 201 Created

Returns the details of the newly created invoice.

{
  "message": "Invoice created successfully",
  "invoice": {
    "id": "uuid-invoice-abc",
    "merchantId": "uuid-merchant-456",
    "invoiceNumber": "INV-MER-00001", // Example generated number
    "amount": 15500000, // Total calculated amount in kobo
    "currency": "NGN",
    "status": "DRAFT",
    "customerEmail": "customer@example.com",
    "customerName": "Jane Doe",
    "customerNote": "Please reference PO #123.",
    "merchantNote": "Follow up if not paid by EOM.",
    "lineItems": [
      { "description": "Web Development Service", "amount": 15000000, "quantity": 1 },
      { "description": "Hosting Fee (Monthly)", "amount": 500000, "quantity": 1 }
    ],
    "dueDate": "2023-11-30T00:00:00.000Z",
    "paidAt": null,
    "sentAt": null,
    "createdAt": "2023-10-27T11:30:00.000Z",
    "updatedAt": "2023-10-27T11:30:00.000Z"
    // Excludes the nested 'merchant' object
  }
}

Errors

• 400 Bad Request: Validation failed (e.g., missing fields, invalid line items).
• 401 Unauthorized: Invalid or missing JWT.
• 404 Not Found: Merchant not found.
• 500 Internal Server Error