Invoices

Create, send, and manage invoices with built-in partial payment support.

Overview

The Invoices API enables you to:

📄 Create invoices - Professional invoices with line items
📧 Send via email/SMS - Deliver invoices to customers
💰 Accept payments - Direct payment links
📊 Partial payments - Accept partial amounts
🔗 Payment links - Unique URLs for each invoice
📱 QR codes - Generate scannable payment codes
📋 PDF generation - Downloadable invoice PDFs
🔔 Automatic reminders - Overdue notifications

Create an Invoice

Endpoint

POST /api/v1/invoices

Request

curl -X POST https://dev.auxcore.net/api/v1/invoices \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "merchant_123",
    "customer": {
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "5551234567"
    },
    "items": [
      {
        "description": "Web Design Services",
        "quantity": 10,
        "unitPrice": 150.00,
        "amount": 1500.00
      },
      {
        "description": "Hosting (Annual)",
        "quantity": 1,
        "unitPrice": 299.00,
        "amount": 299.00
      }
    ],
    "subtotal": 1799.00,
    "tax": 143.92,
    "total": 1942.92,
    "currency": "USD",
    "dueDate": "2026-02-15",
    "allowPartialPayment": true,
    "notes": "Payment due within 15 days",
    "metadata": {
      "projectId": "PRJ-123",
      "poNumber": "PO-456"
    }
  }'

Response

{
  "success": true,
  "data": {
    "invoiceId": "inv_abc123",
    "invoiceNumber": "INV-2026-001",
    "status": "draft",
    "customerId": "cust_789",
    "total": 1942.92,
    "amountDue": 1942.92,
    "amountPaid": 0.00,
    "currency": "USD",
    "dueDate": "2026-02-15T00:00:00Z",
    "allowPartialPayment": true,
    "paymentUrl": "https://pay.auxvault.com/inv_abc123",
    "createdAt": "2026-01-28T00:00:00Z"
  }
}

Send an Invoice

Send invoice via email and/or SMS.

Endpoint

POST /api/v1/invoices/:invoiceId/send

Email Only

curl -X POST https://dev.auxcore.net/api/v1/invoices/inv_abc123/send \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -d '{
    "email": true,
    "subject": "Invoice INV-2026-001 from Acme Corp",
    "message": "Thank you for your business!"
  }'

Email + SMS

curl -X POST https://dev.auxcore.net/api/v1/invoices/inv_abc123/send \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -d '{
    "email": true,
    "sms": true,
    "message": "Your invoice is ready. Click to view and pay."
  }'

Record a Payment

Record a payment against an invoice (full or partial).

Endpoint

POST /api/v1/invoices/:invoiceId/payment

Full Payment

curl -X POST https://dev.auxcore.net/api/v1/invoices/inv_abc123/payment \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -d '{
    "amount": 1942.92,
    "paymentMethod": "card",
    "card": {
      "number": "4111111111111111",
      "expiryMonth": "12",
      "expiryYear": "2027",
      "cvv": "123"
    }
  }'

Partial Payment

curl -X POST https://dev.auxcore.net/api/v1/invoices/inv_abc123/payment \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -d '{
    "amount": 500.00,
    "paymentMethod": "card",
    "note": "First installment"
  }'

Response:

{
  "success": true,
  "data": {
    "paymentId": "pay_xyz789",
    "invoiceId": "inv_abc123",
    "amount": 500.00,
    "amountPaid": 500.00,
    "amountDue": 1442.92,
    "status": "partial",
    "transactionId": "txn_payment_123",
    "paidAt": "2026-01-28T17:00:00Z"
  }
}

Invoice Statuses

Status	Description
`draft`	Invoice created but not sent
`sent`	Invoice sent to customer
`viewed`	Customer viewed the invoice
`partial`	Partially paid
`paid`	Fully paid
`overdue`	Past due date
`cancelled`	Invoice cancelled

Get Invoice

Endpoint

GET /api/v1/invoices/:invoiceId

curl https://dev.auxcore.net/api/v1/invoices/inv_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Response:

{
  "success": true,
  "data": {
    "invoiceId": "inv_abc123",
    "invoiceNumber": "INV-2026-001",
    "status": "partial",
    "customer": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "items": [...],
    "subtotal": 1799.00,
    "tax": 143.92,
    "total": 1942.92,
    "amountPaid": 500.00,
    "amountDue": 1442.92,
    "payments": [
      {
        "amount": 500.00,
        "paidAt": "2026-01-28T17:00:00Z",
        "transactionId": "txn_payment_123"
      }
    ],
    "dueDate": "2026-02-15T00:00:00Z",
    "paymentUrl": "https://pay.auxvault.com/inv_abc123"
  }
}

List Invoices

Endpoint

GET /api/v1/invoices

Query Parameters

Parameter	Type	Description
`page`	integer	Page number
`limit`	integer	Items per page
`status`	string	Filter by status
`customerId`	string	Filter by customer
`startDate`	date	Filter by start date
`endDate`	date	Filter by end date

curl "https://dev.auxcore.net/api/v1/invoices?status=overdue" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Update Invoice

Update an invoice (only if status is draft).

Endpoint

PUT /api/v1/invoices/:invoiceId

curl -X PUT https://dev.auxcore.net/api/v1/invoices/inv_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -d '{
    "items": [...],
    "total": 2000.00,
    "notes": "Updated payment terms"
  }'

Cancel Invoice

Cancel an unpaid invoice.

Endpoint

POST /api/v1/invoices/:invoiceId/cancel

curl -X POST https://dev.auxcore.net/api/v1/invoices/inv_abc123/cancel \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -d '{"reason": "Project cancelled"}'

Generate QR Code

Get a QR code for easy mobile payment.

Endpoint

GET /api/v1/invoices/:invoiceId/qr-code

curl https://dev.auxcore.net/api/v1/invoices/inv_abc123/qr-code \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Response:

{
  "success": true,
  "data": {
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
    "paymentUrl": "https://pay.auxvault.com/inv_abc123"
  }
}

Download PDF

Get invoice as PDF.

Endpoint

GET /api/v1/invoices/:invoiceId/pdf

curl https://dev.auxcore.net/api/v1/invoices/inv_abc123/pdf \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -o invoice.pdf

Partial Payment Flow

AuxVault fully supports partial payments:

Enable partial payments when creating invoice
Customer pays any amount up to remaining balance
Status updates automatically:
- sent → partial (after first payment)
- partial → paid (when fully paid)
Track all payments in payment history
Send reminders for remaining balance

Example Flow

# Create invoice with partial payments enabled
POST /api/v1/invoices
{"total": 1000.00, "allowPartialPayment": true}
# Status: draft, amountDue: 1000.00

# Customer pays $300
POST /api/v1/invoices/inv_123/payment
{"amount": 300.00}
# Status: partial, amountPaid: 300.00, amountDue: 700.00

# Customer pays $700
POST /api/v1/invoices/inv_123/payment
{"amount": 700.00}
# Status: paid, amountPaid: 1000.00, amountDue: 0.00

Webhooks

invoice.created

{
  "type": "invoice.created",
  "data": {
    "invoiceId": "inv_abc123",
    "total": 1942.92
  }
}

invoice.sent

{
  "type": "invoice.sent",
  "data": {
    "invoiceId": "inv_abc123",
    "sentVia": ["email", "sms"]
  }
}

invoice.paid

{
  "type": "invoice.paid",
  "data": {
    "invoiceId": "inv_abc123",
    "amountPaid": 1942.92,
    "transactionId": "txn_payment_123"
  }
}

invoice.partially_paid

{
  "type": "invoice.partially_paid",
  "data": {
    "invoiceId": "inv_abc123",
    "amountPaid": 500.00,
    "amountDue": 1442.92
  }
}

invoice.overdue

{
  "type": "invoice.overdue",
  "data": {
    "invoiceId": "inv_abc123",
    "dueDate": "2026-02-15T00:00:00Z",
    "amountDue": 1942.92
  }
}

Best Practices

✅ DO:

Use clear descriptions in line items
Set reasonable due dates (15-30 days)
Enable partial payments for flexibility
Send reminders for overdue invoices
Provide payment options (card, ACH)
Track payment history

❌ DON'T:

Don't send without reviewing - always preview first
Don't use vague descriptions - be specific
Don't forget tax calculations
Don't skip due dates
Don't update sent invoices - create new one instead

Next Steps

Need help? Contact support@auxvault.com