Invoices

Summary

Invoices allow merchants to send itemized bills to customers with automatic payment link or subscription creation. When an invoice is created, RapidCents generates a PDF, sends it to the customer via email, and creates a Payment Link (one-time) or Subscription (recurring) for the customer to complete payment.

Invoice Lifecycle

1. Create — Merchant creates an invoice with line items, customer, total, tax, discount, and payment type. A Payment Link or Subscription is automatically created.
2. Send — RapidCents sends the invoice email to the customer with a PDF attachment and a “Pay Now” button.
3. Pay — Customer clicks the payment link and completes payment through the hosted payment page. The invoice status automatically updates to PAID.
4. Resend — Merchant can resend the invoice email at any time.

Invoice Statuses

Processing Flow

One-Time Payment

Recurring Payment (Subscription / Installment)

Authentication

All invoice endpoints require a valid Bearer token and are scoped to a business:

Authorization: Bearer {access_token}
Content-Type: application/json

Base URL pattern: /api/{business_id}/invoices

Create Invoice

POST /api/{business}/invoices

Request Body

Payment Info Object

POST /api/{business}/invoices
Content-Type: application/json
Authorization: Bearer {token}

{
  "customerId": "customer-uuid",
  "items": [
    {
      "name": "Web Development",
      "description": "Frontend implementation",
      "quantity": 10,
      "price": 150.00
    },
    {
      "name": "SSL Certificate",
      "quantity": 1,
      "price": 49.99
    }
  ],
  "subTotal": 1549.99,
  "tax": 13,
  "discount": 10,
  "isDiscountPercentage": true,
  "total": 1574.49,
  "dueDate": "2026-03-15",
  "expireOnDue": true,
  "notes": "Thank you for your business!",
  "paymentInfo": {
    "paymentType": "1",
    "merchant_description": "Invoice for web development services"
  }
}

{
  "ok": true,
  "message": "Invoice created successfully",
  "invoice": {
    "id": "invoice-uuid",
    "invoice_number": "INV-20260219-0001",
    "status": "PENDING",
    "total": 1574.49,
    "payment_link_id": "payment-link-uuid",
    "created_at": "2026-02-19T12:00:00.000000Z"
  }
}

List Invoices

GET /api/{business}/invoices

Returns a paginated list of invoices with optional date filters.

{
  "ok": true,
  "invoices": {
    "data": [ /* array of invoice objects */ ],
    "current_page": 1,
    "per_page": 10,
    "total": 25
  },
  "filters": { "fromDate": null, "toDate": null }
}

Get Invoice

GET /api/{business}/invoices/{invoice}

Returns the full details of a single invoice.

Update Invoice

PUT /api/{business}/invoices/{invoice}

Updates an existing invoice. Only editable if the linked payment has not been completed and no active subscription exists.

Delete Invoice

DELETE /api/{business}/invoices/{invoice}

Deletes an invoice along with its linked Payment Link or Subscription. Only deletable if the linked payment has not been completed.

{
  "ok": true,
  "message": "Invoice deleted successfully"
}

Resend Invoice

POST /api/{business}/invoices/{invoice}/resend

Re-sends the invoice email to the customer with the PDF attachment and payment link.

{
  "ok": true,
  "message": "Invoice resent successfully"
}

Export Invoices

GET /api/{business}/invoices/export

Returns all invoices matching the filter criteria in a JSON format suitable for spreadsheet export.

Line Items

Each invoice must contain at least one line item. Items are stored as JSON within the invoice.

The PDF invoice displays line items in a table with columns: Name, Quantity, Unit Price, and Total (quantity × price).

Tax & Discount

Tax

The tax field represents a percentage applied to the subtotal. For example, a tax value of 13 means 13% tax.

// Tax calculation
tax_amount = sub_total × (tax / 100)

Discount

Discounts can be either percentage-based or a fixed dollar amount, controlled by the isDiscountPercentage field:

Payment Types

Due Dates & Expiry

• dueDate — Required. The date by which payment is expected.
• expireOnDue — Optional. When set to true, the linked Payment Link will automatically expire when the due date passes, preventing further payment.

PDF Generation

When an invoice is created, RapidCents automatically generates a PDF document containing:

• Business logo and legal name
• Invoice number and date
• Customer details
• Line items table (Name, Quantity, Unit Price, Total)
• Subtotal, tax, discount, and grand total
• Due date
• Notes (if provided)

The PDF is attached to the customer notification email and can be downloaded from the merchant dashboard.

All Endpoints

Notifications

Error Handling