Orvion
Get started
Developer Guides
Core objects
Payment Receiving
Invoices
Billing
Collections
Payouts
Webhooks & events
SDKs & examples
Administration & security
Changelog & roadmap

Invoices Overview

Meshpay sits between sellers and buyers. This documentation explains how invoices work in the Meshpay system, organized into three clear layers:

  1. Invoices = Records & config (invoices, profiles, analytics)
  2. Collections = Money in (invoice payments, collection automations)
  3. Payouts = Money out (payout ledger, payout automations)

What is an Invoice?

An invoice in Meshpay is a commercial object + x402 snapshot:

"Buyer X owes Seller Y amount A in currency C, for specific items, due on date D."

  • Invoice = commercial object + x402 snapshot (who owes what, how to pay)
  • Collections = money in (how we collect payments for invoices)
  • Payouts = money out (how collected funds are distributed)
  • Profiles = per-network/asset/payout config that invoices inherit from

An invoice is independent of flows - it's a static commercial record with a snapshot of payment configuration.

Invoice Lifecycle

Invoices progress through a well-defined lifecycle:

Draft → Sent → (Partially Paid) → Paid
                    ↓
               Overdue → Canceled

Status Flow

  1. Draft - Invoice is created but not yet sent to the customer
  2. Sent - Invoice has been delivered and is awaiting payment
  3. Partially Paid - Some payments received, balance remaining
  4. Paid - Payment has been fully received
  5. Overdue - Invoice has passed its due date without full payment
  6. Canceled - Invoice has been canceled and will not be paid

State Transitions

  • Draft → Sent: When you explicitly send the invoice
  • Sent → Partially Paid: When a payment is recorded but balance remains
  • Sent/Partially Paid → Paid: When total payments equal or exceed invoice amount
  • Sent → Overdue: Automatically when due_at passes without full payment
  • Any → Canceled: Can be canceled from any state except Paid

Three-Layer Architecture

Meshpay organizes invoicing into three clear categories:

1. Invoices (Records & Config)

Invoices are commercial objects that store:

  • Buyer information and line items
  • Totals (subtotal, discounts, final total)
  • Status (draft, sent, partially_paid, paid, overdue, canceled)
  • x402 payment snapshot (network, asset, pay_to_address)

Invoicing Profiles define per-network/asset/payout configuration:

  • Payment rail settings (network, asset, wallet addresses)
  • Collection mode (direct vs escrow)
  • Default payout splits
  • Partial payment support

Invoices inherit their x402 configuration from a profile at creation time.

2. Collections (Money In)

Collections handle incoming payments:

  • Invoice Payments: Individual payment transactions toward invoices
  • Collection Automations: Flows for dunning, retries, reminders

The basic collection path (SDK + x402) doesn't require automations - they're optional for advanced workflows.

3. Payouts (Money Out)

Payouts handle fund distribution:

  • Payout Ledger: Records of funds distributed to beneficiaries
  • Payout Automations: Flows for batched payouts, routing logic

Splits are configured at the profile level and copied to invoices at creation.

Key Concepts

Organization Scoping

All invoices belong to an organization (org_id). This ensures:

  • Multi-tenancy: Each organization's invoices are isolated
  • RLS Security: Row-level security policies enforce access control
  • Billing Context: Analytics and reporting are scoped per organization

External References

Invoices support an external_id field to link with your CRM, accounting system, or other external systems. This enables:

  • System Integration: Map Meshpay invoices to your existing records
  • Reconciliation: Match payments across systems
  • Reporting: Aggregate data across platforms

Next Steps