Invoices

Monthly invoicing with VAT, lifecycle states, and dunning.

PlatformXe generates monthly invoices for paid plans. All amounts are in Nigerian Naira (NGN) with 7.5% VAT applied.

Invoice lifecycle

State	Description
DRAFT	Invoice generated, not yet finalized
PENDING	Finalized and awaiting payment
PAID	Payment received and confirmed
OVERDUE	Past due date, dunning active
CANCELLED	Manually cancelled

DRAFT → PENDING → PAID
                → OVERDUE → PAID (after retry)
                          → CANCELLED

Viewing invoices

Invoices are accessible via the Tenant Portal billing page and the API.

GET /api/v1/billing/invoices

curl https://api.platformxe.com/api/v1/billing/invoices \
  -H "x-api-key: pxk_live_your_api_key_here"

const invoices = await px.listInvoices();

Response

{
  "success": true,
  "data": {
    "invoices": [
      {
        "id": "inv_abc123",
        "status": "PAID",
        "subtotal": 99000,
        "vat": 7425,
        "total": 106425,
        "currency": "NGN",
        "period": { "start": "2026-03-01", "end": "2026-03-31" },
        "paidAt": "2026-04-02T08:15:00.000Z"
      }
    ]
  }
}

Line items

Each invoice contains line items for plan subscription and any overage charges:

{
  "lineItems": [
    { "description": "Pro Plan — April 2026", "amount": 99000 },
    { "description": "Email overage — 2,500 messages", "amount": 5000 }
  ]
}

Dunning

When an invoice becomes overdue, PlatformXe automatically retries payment:

1. Day 1: Invoice marked overdue, first retry attempted
2. Day 3: Second retry
3. Day 7: Third retry, warning notification sent
4. Day 14: Final retry, service degradation warning

Events

Subscribe to billing events for payment tracking:

• billing.invoice.created — new invoice generated
• billing.invoice.paid — payment confirmed
• billing.invoice.overdue — payment past due