Invoicing

Create invoices, send a payable link to customers over SMS or email, and collect payment via mobile money — with automatic status tracking.

Overview

An invoice represents an amount owed by a customer. AfriRoute generates a hosted payment page and a short link you can deliver by SMS or email. When the customer pays via mobile money, the invoice is marked paid and a webhook fires.

Base URL: https://api.afriroute.ai — Auth: Authorization: Bearer $AFRIROUTE_API_KEY

Endpoints

Create an Invoice

POST /v1/billing/invoices

Field	Type	Required	Description
customer	object	Yes	name, phone_number, optional email
currency	string	Yes	ISO 4217 code
line_items	array	Yes	description, quantity, unit_price
due_date	string	No	ISO date
delivery	array	No	sms, email

curl -X POST https://api.afriroute.ai/api/v1/billing/invoices \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": { "name": "Abel Tesfaye", "phone_number": "+251911234567" },
    "currency": "ETB",
    "line_items": [
      { "description": "Consulting (10 hrs)", "quantity": 10, "unit_price": 200 }
    ],
    "due_date": "2026-06-15",
    "delivery": ["sms"]
  }'

{
  "invoice_id": "inv_001",
  "status": "sent",
  "total": 2000.00,
  "currency": "ETB",
  "pay_url": "https://pay.afriroute.ai/i/inv_001",
  "due_date": "2026-06-15"
}

Send / Resend an Invoice

POST /v1/billing/invoices/:invoice_id/send

await fetch('https://api.afriroute.ai/api/v1/billing/invoices/inv_001/send', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer $AFRIROUTE_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ delivery: ['sms', 'email'] })
});

Get an Invoice

GET /v1/billing/invoices/:invoice_id

import requests

r = requests.get(
    'https://api.afriroute.ai/api/v1/billing/invoices/inv_001',
    headers={'Authorization': 'Bearer $AFRIROUTE_API_KEY'}
)
print(r.json())

{
  "invoice_id": "inv_001",
  "status": "paid",
  "total": 2000.00,
  "currency": "ETB",
  "paid_at": "2026-05-28T11:00:00Z",
  "payment_id": "pay_abc123",
  "pdf_url": "https://invoices.afriroute.ai/inv_001.pdf"
}

Void an Invoice

POST /v1/billing/invoices/:invoice_id/void

curl -X POST https://api.afriroute.ai/api/v1/billing/invoices/inv_001/void \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY"

Invoice Statuses

Status	Meaning
draft	Created, not yet sent
sent	Delivered to the customer
paid	Fully paid
overdue	Past due_date, unpaid
void	Cancelled

Best Practices

• Deliver by SMS in markets where email adoption is low; include the short pay_url.
• Set a clear due_date and let AfriRoute send automatic overdue reminders.
• Reconcile paid invoices using the linked payment_id rather than amount matching.
• Void instead of deleting so you keep an auditable record of cancelled invoices.

Error Handling

Code	Description	Action
INVOICE_ALREADY_PAID	Cannot modify a paid invoice	Issue a credit/refund instead
INVALID_LINE_ITEM	Missing price/quantity	Validate line items
DELIVERY_FAILED	SMS/email could not be sent	Verify contact details

Related Links

• Billing
• Mobile Money
• Wallet
• Payments API Reference

---

Last Updated: May 2026