SplitRoute Logo
SplitRoute

Perpetual Invoices

Perpetual invoices are a special type of invoice that doesn't expire and can receive multiple payments over time. This document explains how to create and use perpetual invoices.

What Are Perpetual Invoices?

Unlike standard invoices that expire after a set period (typically 1 hour), perpetual invoices:

  • Never expire automatically
  • Can receive multiple payments
  • Remain active until manually cancelled or deleted
  • Process each payment according to the configured distribution rules

Creating a Perpetual Invoice

To create a perpetual invoice, add the is_perpetual flag to your invoice creation request:

JSON
1{
2  "is_perpetual":  true,
3  "destinations":  [
4    {
5      "account":  "nano_123...",
6      "primary":  true
7    },
8    {
9      "account":  "nano_27g9ge50ri4",
10      "percentage":  10,
11      "description":  "Platform fee (10%)"
12    }
13  ]
14}

Important Notes:

  1. For perpetual invoices, the nominal_amount is optional and will be ignored if provided.
  2. The invoice doesn't have a fixed total amount expectation, as it can receive multiple payments.
  3. Each payment received is distributed according to the specified destinations.

Invoice Type

When you create a perpetual invoice, the response includes:

JSON
1{
2  "invoice_type":  "PERPETUAL_OPTIONAL"
3}

This indicates it's a perpetual invoice without a fixed amount expectation.

Payment Distribution for Perpetual Invoices

For each payment received:

  1. The service fee is calculated on the payment amount
  2. Percentage-based destinations receive their share of the remaining amount after the fee
  3. The primary destination receives whatever remains

Note: Fixed amount distributions are not recommended for perpetual invoices since the payment amount is unknown and variable.

Lifecycle Differences

Perpetual invoices follow a modified lifecycle:

  1. Created: Invoice is created and ready to receive payments
  2. Paid: Payments are received and processed individually
  3. Forwarded: Each payment is forwarded to destinations according to the distribution rules
  4. Done: The invoice remains active, ready to receive more payments (unless manually cancelled)

Unlike standard invoices, perpetual invoices don't have an "Expired" state since they don't expire automatically.

Example API Request

JSON
1POST /api/v1/invoices
2
3{
4  "is_perpetual":  true,
5  "nominal_currency":  "USD",
6  "destinations":  [
7    {
8      "account":  "nano_123...",
9      "primary":  true
10    },
11    {
12      "account":  "nano_26qjv4lmg2s",
13      "percentage":  20,
14      "description":  "Partnership fee (20%)"
15    }
16  ],
17  "webhook_url":  "https://your-server.com/webhook",
18  "reference":  "donation-page-abc123"
19}

Example API Response

JSON
1{
2  "invoice_id":  "INV_2025_03_d1447da3e9ff90cd3822",
3  "secret_id":  "INV_SECRET_02122c244c4a33453dbc4",
4  "account_address":  "nano_1payment_address",
5  "nominal_currency":  "USD",
6  "formatted_currency":  "XNO",
7  "invoice_type":  "PERPETUAL_OPTIONAL",
8  "required":  {
9    "unit_amount":  null,
10    "formatted_amount":  null,
11    "nominal_amount":  null
12  },
13  "received":  {
14    "unit_amount":  "0",
15    "formatted_amount":  "0",
16    "nominal_amount":  "0"
17  },
18  "exchange_rate":  "81.25",
19  "expires_at":  null,
20  "destinations":  [
21    {
22      "type":  "primary",
23      "account":  "nano_123...",
24      "unit_amount":  null,
25      "formatted_amount":  null,
26      "nominal_amount":  null
27    },
28    {
29      "type":  "percentage",
30      "account":  "nano_26qjv4lmg2s",
31      "unit_amount":  null,
32      "formatted_amount":  null,
33      "nominal_amount":  null,
34      "percentage":  20,
35      "description":  "Partnership fee (20%)"
36    },
37    {
38      "type":  "service_fee",
39      "account":  "nano_1nowapi9w5hx3d4wb9swa88p8dd7tsf8xsycob3owy855sai6j9zuyztjzdj",
40      "unit_amount":  null,
41      "formatted_amount":  null,
42      "nominal_amount":  null,
43      "description":  "Service fee"
44    }
45  ],
46  "service_fee_rate":  "0.50",
47  "show_qr":  false,
48  "is_simulation":  false,
49  "is_perpetual":  true,
50  "is_pending":  false,
51  "is_paid":  false,
52  "is_forwarded":  false,
53  "is_done":  false,
54  "is_expired":  false,
55  "is_overpaid":  false,
56  "uri_rfc_8905":  "payto:nano/nano_1payment_address",
57  "uri_nano":  "nano:nano_1payment_address"
58}

Use Cases for Perpetual Invoices

Perpetual invoices are ideal for:

  • Donation pages
  • Tip jars
  • Ongoing subscriptions with variable amounts
  • Reusable payment addresses for repeat customers

WebSocket and Webhook Events

Like standard invoices, perpetual invoices generate WebSocket and Webhook events:

  • invoice.created - Invoice has been created
  • invoice.paid - A payment has been received
  • invoice.forwarded - A payment has been forwarded to destinations

The main difference is that perpetual invoices will continue generating these events for each payment received, rather than completing after the first full payment.

Related Topics