Invoices and Orders

Invoices represent payment requests sent to customers. RevKeen automatically creates invoices for subscriptions, but you can also create manual invoices for one-time charges. Orders are fulfillment containers created when invoices with deliverable products are paid.

Invoice Lifecycle

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

Invoice Statuses

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. Each line item includes the billing interval (e.g., "Billed monthly") so customers always know their recurring schedule.

Checkout Invoices

Created when a customer completes a checkout. If the checkout contains products with physical or digital fulfillment, an order is also automatically created when the invoice is paid.

Creating Invoices

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

  // Line items
  lineItems: [
    {
      description: 'Consulting - February 2026',
      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-2026-0001

invoice = client.invoices.create(
    customer_id="cus_xxxxxxxx",
    currency="USD",
    due_date="2026-03-15T00:00:00Z",

    line_items=[
        {
            "description": "Consulting - February 2026",
            "amount_minor": 50000,
            "quantity": 1,
        },
        {
            "description": "Travel expenses",
            "amount_minor": 15000,
            "quantity": 1,
        },
    ],

    memo="Thank you for your business!",
    footer="Payment due within 30 days."
)

print(invoice.data.invoice_number)  # INV-2026-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.

Adding Line Items

// Add a line item to a draft invoice
await client.invoices.addLineItem('inv_xxxxxxxx', {
  description: 'Additional service',
  amountMinor: 25000,
  quantity: 1,
});

// Add from a product
await client.invoices.addLineItem('inv_xxxxxxxx', {
  productId: 'prod_xxxxxxxx',
  quantity: 2,
});

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:

1. Create invoice as draft
2. Click Submit for Approval
3. Approver reviews the invoice
4. Approves -- Invoice moves to "Approved" status
5. Or Rejects -- Invoice returns to "Draft" with notes
6. Send the approved invoice to the customer

Voiding Invoices

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

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

Subscription Invoices

RevKeen automatically creates invoices for subscriptions:

• Created at start of each billing period
• Automatically finalized and charged
• Past due invoices trigger dunning emails
• Failed payments retry according to your retry schedule

// List invoices for a subscription
const invoices = await client.invoices.list({
  subscriptionId: 'sub_xxxxxxxx',
});

Invoice Best Practices

1. Clear line item descriptions -- Customers should understand exactly what they're being charged for.
2. Reasonable due dates -- 14-30 days is typical; adjust based on your industry.
3. Follow up promptly -- Send reminders for overdue invoices within a few days.
4. Use the approval workflow -- For large invoices, get internal review before sending.
5. Add helpful notes -- Use memo and footer fields for payment instructions or thank you messages.

Invoice Line Items

Invoice Line Items represent individual charges on an invoice. Each line item tracks where it came from (its source), enabling accurate revenue attribution and audit trails.

What is a Line Item?

A line item is a single entry on an invoice that describes a specific charge. Each line item has:

• Description -- What the charge is for
• Amount -- How much is being charged
• Quantity -- Number of units
• Source Type -- Where the line item originated
• Source Reference -- Link to the originating entity

Source Types

Line items can originate from different sources, tracked by the source_type field:

Line Item Fields

Adding Line Items

From a Product Price

await client.invoices.addLineItem('inv_xxxxxxxx', {
  priceId: 'price_xxxxxxxx',
  quantity: 2,
});
// Creates line item with source_type: 'price'

Custom Line Item (Adjustment)

await client.invoices.addLineItem('inv_xxxxxxxx', {
  description: 'Rush delivery fee',
  amountMinor: 5000, // $50.00
  quantity: 1,
});
// Creates line item with source_type: 'adjustment'

Credit / Discount Line Item

await client.invoices.addLineItem('inv_xxxxxxxx', {
  description: 'Loyalty discount - 10%',
  amountMinor: -2500, // -$25.00 credit
  quantity: 1,
});

Billing Interval on Line Items

For recurring items, the billing interval is stored directly on the line item as a snapshot from the product or subscription at the time of creation. This ensures invoices and receipts always show the correct billing frequency, even if the product is later changed.

The billing interval is displayed on:

• Invoice PDFs (below the line item description, e.g., "Billed monthly")
• Payment receipts
• Public invoice pages (guest view)
• Dashboard invoice preview

For invoices created before the billing interval feature, RevKeen automatically looks up the interval from the linked product as a fallback.

Automatic Line Items

Some line items are created automatically:

• Subscription Renewals -- When a subscription renews, line items are automatically created from each subscription item. The period_start and period_end fields indicate the billing period covered, and the billing_interval shows the recurring frequency.
• Checkout Completions -- When a customer completes checkout, order line items become invoice line items with source_type: order_line_item.
• Prorations -- When a subscription changes mid-cycle, prorated adjustments are added as line items to credit unused time or charge for upgrades.

Why Source Tracking Matters

1. Revenue Attribution -- Know exactly which products and subscriptions are generating revenue.
2. Audit Trail -- Trace any charge back to its origin for compliance and reconciliation.
3. Refund Processing -- Refund specific line items rather than entire invoices.
4. Reporting -- Generate accurate reports by product, subscription, or customer.

Line items cannot be modified after an invoice is finalized. To make changes, void the invoice and create a new one.

Orders

Orders are fulfillment containers in RevKeen. When an invoice containing products with a fulfillment_type of physical or digital is paid, an Order is automatically created to track delivery. This applies to both one-time purchases and recurring subscription renewals.

What is an Order?

An Order is a fulfillment container that tracks the delivery of products. Unlike invoices (which track the commercial/financial side), orders track the physical or digital delivery of goods. Orders are created automatically when an invoice containing fulfillable items is paid.

Products in RevKeen have two dimensions: billing type (one_time or recurring) and fulfillment type (none, physical, or digital). Orders are created for any product where fulfillment_type is not "none", regardless of billing type.

Orders are created from:

• Invoice payment (when invoice contains fulfillable products)
• Subscription renewals (for recurring products with physical/digital fulfillment)
• Checkout link completions (for products with fulfillment)
• Direct API calls
• Manual creation in the dashboard

Invoice vs Order

Order Statuses

Order Line Items

Each order contains one or more line items representing products purchased:

Fulfillment Tracking

Fulfillment tracking depends on the product's fulfillment_type:

Physical Products -- Track shipping status, carrier, and tracking numbers. Flow: pending -> shipped -> delivered.

Digital Products -- Typically fulfilled immediately with download links or access granted. Flow: pending -> delivered (automatic).

No Fulfillment (fulfillment_type: none) -- Products with no fulfillment type (e.g., SaaS subscriptions, memberships) do not create orders. The invoice alone tracks the purchase.

Creating Orders via API

const order = await client.orders.create({
  customerId: 'cus_xxxxxxxx',
  currency: 'USD',

  lineItems: [
    {
      priceId: 'price_xxxxxxxx',
      quantity: 2,
    },
    {
      priceId: 'price_yyyyyyyy',
      quantity: 1,
    },
  ],

  // Optional: Apply a discount
  discountId: 'disc_xxxxxxxx',

  // Optional: Shipping address (for physical products)
  shippingAddress: {
    line1: '123 Main St',
    city: 'San Francisco',
    state: 'CA',
    postalCode: '94102',
    country: 'US',
  },
});

console.log(order.data.id); // ord_xxxxxxxx

Managing Orders in Dashboard

Navigate to Sales > Orders to:

• View all orders with filtering by status, date, customer
• Click an order to view details and line items
• Update fulfillment status for physical products
• Add tracking information for shipments
• Process refunds for paid orders
• Cancel pending orders

Order Events

Related

• Customers -- Customer profiles and billing info
• Subscriptions -- How subscriptions generate invoices
• Payments and Refunds -- Handle invoice payments