Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.dubupay.com/llms.txt

Use this file to discover all available pages before exploring further.

The invoices API lets you generate professional payment requests for your customers. Each invoice contains customer details, a list of line items (which can reference your product catalog or be entered as custom line items), and optional due dates and notes. Once an invoice is ready, you can send it directly to your customer’s email address. Dubu tracks payment status automatically — when a customer pays via a checkout link linked to the invoice, the status updates to paid. All routes require authentication.

​
Invoice statuses

StatusDescription
draftInvoice is being prepared and has not been sent.
pendingInvoice has been sent and is awaiting payment.
paidPayment has been received.
overdueThe due date has passed without payment.
canceledInvoice was manually canceled.

​
Create an invoice

POST /invoices
Creates a new invoice with at least one line item. You can include line items inline at creation time, and add or remove them later using the line-items sub-endpoints.

​
Request body

​
title
string
required
Invoice title shown to the customer. Maximum 255 characters.
​
customer_name
string
required
Full name of the customer being billed. Maximum 255 characters.
​
customer_email
string
required
Email address of the customer. Used when sending the invoice by email.
​
customer_id
string
Optional UUID of an existing customer in your account. Links the invoice to a saved customer record.
​
currency
string
Invoice currency: NGN or USD. Defaults to your account currency.
​
issue_date
string
Invoice issue date in ISO 8601 format (e.g. 2024-01-15). Defaults to today.
​
due_date
string
Payment due date in ISO 8601 format. Optional. When set, Dubu will mark the invoice as overdue after this date if unpaid.
​
notes
string
Optional notes or payment instructions displayed on the invoice. Maximum 2,000 characters.
​
line_items
array
required
At least one line item is required.

​
Example

curl -X POST https://api.dubupay.com/api/v1/invoices \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Web Design Services — January 2024",
    "customer_name": "Amaka Okonkwo",
    "customer_email": "amaka@example.com",
    "currency": "NGN",
    "due_date": "2024-02-01",
    "line_items": [
      {
        "description": "Homepage redesign",
        "quantity": 1,
        "unit_price": 350000
      },
      {
        "description": "Mobile responsive implementation",
        "quantity": 1,
        "unit_price": 150000
      }
    ]
  }'
Returns 201 Created with the invoice object.

​
Invoice response fields

​
id
string
Invoice UUID.
​
invoice_number
string
Human-readable invoice number (e.g. INV-0001).
​
title
string
Invoice title.
​
customer_name
string
Customer full name.
​
customer_email
string
Customer email.
​
currency
string
Invoice currency.
​
status
string
Current invoice status.
​
total_amount
number
Total invoice amount including all taxes and discounts.
​
issue_date
string
Invoice issue date.
​
due_date
string
Payment due date. null if not set.
​
paid_at
string
ISO 8601 timestamp of when payment was received. null until paid.
​
line_items
array
Array of line item objects attached to this invoice.

​
List invoices

GET /invoices

​
Query parameters

​
status
string
Filter by status: draft, pending, paid, overdue, or canceled.
​
search
string
Search by customer name, email, or invoice number.
​
page
number
Page number (1-indexed).
​
limit
number
Results per page. Maximum 100.

​
Example

curl "https://api.dubupay.com/api/v1/invoices?status=pending&limit=50" \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY"

​
Get an invoice

GET /invoices/:id
​
id
string
required
UUID of the invoice to retrieve.
curl https://api.dubupay.com/api/v1/invoices/inv_uuid_here \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY"

​
Update an invoice

PATCH /invoices/:id
Update the invoice metadata. You can only update invoices that are in draft or pending status. Use the line-items endpoints to modify line items.
​
id
string
required
UUID of the invoice to update.
​
title
string
New invoice title.
​
customer_name
string
Updated customer name.
​
customer_email
string
Updated customer email.
​
currency
string
NGN or USD.
​
issue_date
string
Updated issue date.
​
due_date
string
Updated due date. Pass null to remove it.
​
notes
string
Updated notes. Pass null to clear.
​
status
string
Manually set status to draft, pending, or canceled.

​
Delete an invoice

DELETE /invoices/:id
Permanently deletes an invoice. You cannot delete invoices with paid status.
​
id
string
required
UUID of the invoice to delete.
curl -X DELETE https://api.dubupay.com/api/v1/invoices/inv_uuid_here \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY"

​
Send invoice by email

POST /invoices/:id/send
Sends the invoice to the customer’s email address on file. The invoice must have a valid customer_email. Calling this endpoint also transitions the invoice status from draft to pending.
​
id
string
required
UUID of the invoice to send.
curl -X POST https://api.dubupay.com/api/v1/invoices/inv_uuid_here/send \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY"

​
Add a line item

POST /invoices/:id/line-items
Append a new line item to an existing invoice. You can add custom line items or reference a product from your catalog.
​
id
string
required
UUID of the invoice.
​
description
string
required
Line item description. Maximum 500 characters.
​
quantity
number
required
Number of units.
​
unit_price
number
required
Price per unit.
​
product_id
string
Optional product UUID. When provided, the description and pricing default to the product’s values.
​
tax_type
string
none, percentage, or fixed.
​
tax_rate
number
Tax amount for this line item.
​
discount_type
string
none, percentage, or fixed.
​
discount
number
Discount amount for this line item.
Returns 201 Created with the new line item object.

​
Remove a line item

DELETE /invoices/:id/line-items/:lineItemId
Remove a specific line item from an invoice. The invoice total is recalculated automatically.
​
id
string
required
UUID of the invoice.
​
lineItemId
string
required
UUID of the line item to remove.
curl -X DELETE \
  https://api.dubupay.com/api/v1/invoices/inv_uuid_here/line-items/li_uuid_here \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY"