Quick Start Guide

Let’s create a simple invoice for a monthly subscription:

nodejs

const invoice = await modempay.invoices.create({
  amount: 250,
  customer_name: "John Doe",
  customer_email: "[e-mail]",
  customer_phone: "[phone]",
  due_date: "2025-12-31",
  notes: "Monthly Pro Plan Subscription - December 2025"
});

console.log('Invoice created:', invoice.reference);
console.log('Payment link:', invoice.payment_link);

What Happens Next?

1. Invoice is created with status not-paid
2. Customer automatically receives an email with the invoice
3. Customer can pay via the payment_link
4. You receive a paymentrequest.success webhook when payment completes
5. If unpaid by due_date, status changes to overdue (production only)

Create a Professional Invoice

For detailed billing with line items (perfect for usage-based subscriptions):

nodejs

const invoice = await modempay.invoices.create({
  amount: 0, // This will be auto-calculated from line items
  customer_name: "Adama Sanneh",
  customer_email: "[e-mail]",
  line_items: [
    {
      item: "Pro Plan Base Fee",
      quantity: 1,
      unit_price: 500
    },
    {
      item: "Additional API Calls",
      quantity: 50,
      unit_price: 0.50 // 50 bututs per call
    }
  ],
  discount: {
    type: "percentage",
    amount: 10 // 10% discount
  },
  due_date: "2025-12-31",
  notes: "December 2025 - Pro Plan + Overages"
});

Line Item Breakdown

The invoice automatically calculates:

• Subtotal: Sum of all line items (500 + [50 * 0.50] = 500 + 25 = 525)
• Discount: 10% off subtotal (525)
• Total: Subtotal minus discount (472.5)

Work with Drafts

Create a draft invoice to review before sending:

nodejs

// Create draft
const draft = await modempay.invoices.draft({
  amount: 500,
  customer_name: "John Doe",
  customer_email: "[e-mail]",
  due_date: "2025-12-31"
});

// Review and modify if needed
const updated = await modempay.invoices.update(draft.id, {
  amount: 550,
  notes: "Updated pricing"
});

// Send when ready
await modempay.invoices.sendDraftInvoice(draft.id);

Draft invoices are not sent to customers and have sent_date: null. Use sendDraftInvoice() to publish them.

Check Invoice Status

Retrieve an invoice to check its current status:

nodejs

const invoice = await modempay.invoices.retrieve('invoice_id_here');

console.log('Status:', invoice.status); // "not-paid" | "paid" | "overdue"
console.log('Amount:', invoice.amount);
console.log('Paid date:', invoice.paid_date); // null if not paid

List All Invoices

Fetch invoices with pagination:

nodejs

const invoices = await modempay.invoices.list({
  limit: 20,
  offset: 0
});

console.log('Total invoices:', invoices.meta.total);
console.log('Invoices:', invoices.data);

Send Payment Reminders

Remind customers about unpaid invoices:

nodejs

await modempay.invoices.sendReminder('invoice_id_here');

The system tracks reminder_count to prevent spam. Use reminders judiciously.

Handle Webhooks

Set up webhook handling to respond to invoice events:

nodejs

// In your webhook endpoint
app.post('/webhooks/modempay', (req, res) => {
  const event = modempay.webhooks.composeEventDetails(
      req.body,
      req.headers["x-modem-signature"],
      process.env.WEBHOOK_SECRET
  );

  switch(event.event) {
    case 'paymentrequest.success':
      // Grant subscription access
      console.log('Invoice paid:', event.payload.reference);
      break;
      
    case 'invoice.overdue':
      // Pause subscription or send notice
      console.log('Invoice overdue:', event.payload.reference);
      break;
  }
  
  res.sendStatus(200);
});

Always return a 200 status code to acknowledge receipt of webhooks.

Subscription Use Case Example

Here’s a complete monthly subscription flow:

async function billMonthlySubscription(customerId: string) {
  // Create invoice for this month
  const invoice = await modempay.invoices.create({
    amount: 2500,
    customer: customerId,
    due_date: getEndOfMonth(), // Helper function
    notes: `Monthly Pro Plan - ${getCurrentMonth()}`,
    callback_url: "https://yourapp.com/subscription/confirm"
  });
  
  // Invoice is automatically sent to customer
  // You'll receive webhook when paid or overdue
  
  return invoice;
}

Common Questions

Q: When is the invoice sent to the customer?
A: Immediately upon creation (for published invoices) or when you call sendDraftInvoice() for drafts.

Q: How do I know when an invoice is paid?
A: You’ll receive a paymentrequest.success webhook event. You can also poll using retrieve().

Q: What happens if a customer doesn’t pay by the due date?
A: In production mode, the invoice status automatically changes to overdue and you receive an invoice.overdue webhook.

Q: Can I manually mark an invoice as paid?
A: Yes, use modempay.invoices.pay(id) for offline payments.

---

Need help? Contact support at [e-mail].