Invoices

Payment requests with line items, status tracking, and full lifecycle management

Invoices represent payment requests sent to customers. RevKeen automatically creates invoices for subscriptions, but you can also create manual invoices for one-time charges, custom services, or any other billing need.

Invoice Lifecycle

┌─────────┐     ┌──────────────────┐     ┌──────────┐     ┌──────┐
│  DRAFT  │────▶│ PENDING_APPROVAL │────▶│ APPROVED │────▶│ SENT │
└─────────┘     └──────────────────┘     └──────────┘     └──┬───┘
                                                             │
                         ┌───────────────────────────────────┘
                         │
                         ▼
              ┌─────────────────────┐
              │   AWAITING PAYMENT  │
              └──────────┬──────────┘
                         │
         ┌───────────────┼───────────────┐
         │               │               │
         ▼               ▼               ▼
   ┌───────────┐   ┌───────────┐   ┌─────────┐
   │   PAID    │   │ PARTIALLY │   │ OVERDUE │
   │           │   │   PAID    │   │         │
   └───────────┘   └───────────┘   └─────────┘

Invoice Statuses

Status	Description	Available Actions
`draft`	Being prepared, fully editable	Edit, add items, delete, submit
`pending_approval`	Submitted for internal review	Approve, reject, edit
`approved`	Ready to send to customer	Send, void
`sent`	Delivered to customer	Resend, record payment, void
`partially_paid`	Some payment received	Record payment, send reminder
`paid`	Fully paid	Issue refund
`overdue`	Past due date, unpaid	Send reminder, void
`voided`	Cancelled	None
`refunded`	Payment returned	None
`uncollectible`	Written off as bad debt	None

Invoice Types

Manual Invoices

Created by you through the dashboard or API. Use for custom charges, consulting fees, one-time services, or any billing that doesn't fit a subscription model.

Subscription Invoices

Automatically generated at each billing period. Includes subscription items and any usage charges. Payment is attempted automatically using the customer's saved payment method.

Order Invoices

Created when a customer completes a one-time purchase. Includes order line items and is typically paid immediately at checkout.

Creating Invoices

const invoice = await client.invoices.create({
  customerId: 'cus_xxxxxxxx',
  currency: 'USD',
  dueDate: '2025-02-15T00:00:00Z',

  // Line items
  lineItems: [
    {
      description: 'Consulting - January 2025',
      amountMinor: 50000, // $500.00
      quantity: 1,
    },
    {
      description: 'Travel expenses',
      amountMinor: 15000, // $150.00
      quantity: 1,
    },
  ],

  // Optional
  memo: 'Thank you for your business!',
  footer: 'Payment due within 30 days.',
});

console.log(invoice.data.invoiceNumber); // INV-2025-0001

Sending Invoices

// Finalize the invoice (moves from draft to approved/sent)
const invoice = await client.invoices.finalize('inv_xxxxxxxx');

// Send via email
await client.invoices.send('inv_xxxxxxxx', {
  to: ['john@example.com', 'billing@example.com'],
  cc: ['accountant@yourcompany.com'],
});

The invoice email includes a secure payment link where customers can view and pay online.

Recording Payments

For payments made outside of RevKeen (cash, check, bank transfer):

// Record an external payment
await client.invoices.pay('inv_xxxxxxxx', {
  amountMinor: 65000,
  paymentMethod: 'cash',
  note: 'Paid via check #1234',
});

// Or pay with a saved card
await client.invoices.pay('inv_xxxxxxxx', {
  paymentMethodId: 'pm_xxxxxxxx',
});

Approval Workflow

For businesses requiring review before sending invoices:

Create invoice as draft
Click Submit for Approval
Approver reviews the invoice
Approves → Invoice moves to "Approved" status
Or Rejects → Invoice returns to "Draft" with notes
Send the approved invoice to the customer

Voiding Invoices

To cancel an unpaid invoice:

await client.invoices.void('inv_xxxxxxxx', {
  reason: 'Duplicate invoice',
});

Paid invoices cannot be voided. Use refunds instead to return payment.

Best Practices

Clear line item descriptions

Customers should understand exactly what they're being charged for

Reasonable due dates

14-30 days is typical; adjust based on your industry

Follow up promptly

Send reminders for overdue invoices within a few days

Use the approval workflow

For large invoices, get internal review before sending

Add helpful notes

Use memo and footer fields for payment instructions or thank you messages

📋

Invoice Line Items

Understanding line item sources and tracking

📄

Invoices Dashboard

Managing invoices in the dashboard