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.

If the Dashboard invoice list cannot load, use Retry invoices. Previously loaded rows may remain visible with a warning. An unavailable amount or currency is shown as Amount unavailable; a confirmed zero remains zero in the invoice's currency.

In General Settings, failed Invoice or Payments reads show a retry message before the dependent configuration forms. Retry loading the saved settings before making changes.

How customers pay an invoice

Payers open the hosted invoice page at /i/{token} on the checkout app. That page is Invoice V6: the invoice itself, plus payment rails (card, Direct Debit, wallets when enabled). It is not a checkout-link hop.

Paying an invoice by Direct Debit is a collection after the mandate is Active and advance notice is given. Invoice V6 shows that timing in the pay box: no money leaves the account today, the collection date when known, the bank statement name, and Card as the instant alternative when that rail is enabled. Sending a mandate from the invoice does not debit it. See Start from an invoice.

• Share the hosted URL from the invoice email or copy it from the dashboard.
• ?action=pay expands and scrolls to payment.
• Creating a checkout session for an already-issued invoice is the wrong default — use the invoice token.

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.

Currency on API requests

Invoice creation and external invoice upsert requests, including batch items, require an explicit currency. Omitting it no longer chooses USD. Send a three-letter ASCII currency code with supported minor-unit metadata; lowercase codes are normalized to uppercase. Missing, blank or unknown codes are rejected before invoice persistence.

Currency metadata support does not guarantee a payment processor supports that currency. Existing historical invoices remain renderable. Integrations should send the invoice's actual currency on every upsert, including status updates.

Creating Invoices

The public API creates an invoice for a customer with a total amount. Build invoices with individual line items in the dashboard invoice editor.

import { RevKeenClient } from "@revkeen/sdk";

const client = new RevKeenClient({ apiKey: process.env.REVKEEN_API_KEY! });

const { data: invoice } = await client.invoices.create({
  customer_uuid: "11111111-1111-4111-8111-111111111111",
  total_minor: 65000, // £650.00
  currency: "GBP",
  due_date: "2026-10-31",
  allowed_methods: ["card", "direct_debit"], // optional: narrow the payment rails
});

See Create an invoice for every field.

Sending Invoices

// Finalize the draft: assigns the invoice number and locks the financial fields
await client.invoices.finalize(invoice.id);

// Send it to the customer's email on file
await client.invoices.send(invoice.id, { channel: "email" });

The invoice email, SMS, or WhatsApp message includes a hosted invoice URL. The customer opens /i/{token} on the checkout app — they do not hop to a generic checkout-link page to settle an already-issued invoice. Optional query ?action=pay scrolls the payment section into view.

Recurring lines and billing schedule

When you add a recurring product to an invoice, RevKeen shows the product billing schedule immediately under Using product schedule. That is the default: the invoice does not store a second thinner schedule.

• Customize for this invoice off — no extra schedule fields. Terms stay absent, so subscription creation falls back to the product template.
• Customize for this invoice on — the same Configure Billing Schedule settings as the product (interval, first charge, trial, until cancelled or a fixed number of payments, collection). The heading becomes Invoice billing schedule. Those terms are stored on the invoice and win at subscription creation.

Shortcuts such as 12 payments or Start when paid fill that shared model. They are not a separate invoice-only dialect.

On invoices with more than one recurring product, the first recurring line with a reachable product seeds the summary and the customize starting point.

After the invoice is paid, the created subscription freezes the resolved schedule. Later product edits do not change it.

When you record a payment yourself (cash, bank transfer, or another method outside RevKeen) on an invoice with recurring products, the subscription is created in the invoice's currency. If the subscription cannot be created, the payment is still recorded and the dashboard shows a warning saying the subscription was not created.

Adding Line Items

Add, edit and remove line items on a draft invoice in the dashboard invoice editor. Line-item editing is not part of the public API yet.

Recording Payments

The invoice detail page's Mark paid action records the payment in the invoice's currency and confirms success after the payment has been recorded. This action does not support backdated payments; a supplied payment date is rejected without recording the payment. Approval alone does not send an invoice—use the separate send action when you are ready to deliver it.

Use Mark paid for payments made outside of RevKeen (cash, cheque, bank transfer). There is no public API call that records or charges an invoice payment. To take a card payment through the API, use a payment intent.

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 a customer's invoices
const { data: invoices } = await client.invoices.list({
  customerId: "11111111-1111-4111-8111-111111111111",
});

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

Line items are added in the dashboard invoice editor, from a product price, as a custom adjustment, or as a negative credit line. The line's source_type records which (price, adjustment, and so on).

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.

How Orders Are Created

Orders are created for you when a checkout that includes fulfillable products is paid. There is no API for creating or paying an order directly: sell through a checkout session or a payment link, then manage the orders it produces in the dashboard.

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

These public webhook events cover orders. Orders are managed in the dashboard; there is no public orders API yet.

Related

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

Owner: david · Reviewed 30 Sep 2026 · Next review 30 Oct 2026