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.

Dubu Pay’s invoicing API lets you create professional invoices, attach line items, and deliver them to customers directly by email. Invoices go through a clear status lifecycle — from draft through to paid — and payments can be collected via virtual bank accounts or checkout links. This guide covers the full flow from creation to delivery.

​
Invoice statuses

StatusMeaning
draftCreated but not yet sent to the customer
pendingSent; awaiting payment
paidPayment confirmed
overduePast the due date with no payment
canceledVoided; no longer payable

​
Create an invoice

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 — November 2024",
    "customer_name": "Amara Okafor",
    "customer_email": "amara@example.com",
    "currency": "NGN",
    "issue_date": "2024-11-01",
    "due_date": "2024-11-15",
    "notes": "Payment is due within 14 days. Bank transfer only.",
    "line_items": [
      {
        "description": "Homepage design",
        "quantity": 1,
        "unit_price": 150000,
        "tax_type": "percentage",
        "tax_rate": 7.5
      },
      {
        "description": "Mobile responsive layout",
        "quantity": 1,
        "unit_price": 75000
      }
    ]
  }'
Request fields:
FieldTypeRequiredDescription
titlestringYesInvoice title (max 255 chars)
customer_namestringYesRecipient’s display name
customer_emailstringYesRecipient’s email address
customer_idstringNoLink to an existing Dubu customer record
currencystringNoNGN or USD. Defaults to NGN
issue_datestringNoISO date string (e.g. 2024-11-01)
due_datestringNoISO date string
notesstringNoFreeform notes shown on the invoice (max 2000 chars)
line_itemsarrayYesAt least one line item is required
Line item fields:
FieldTypeRequiredDescription
descriptionstringYesItem description (max 500 chars)
quantityintegerYesMust be a positive integer
unit_pricenumberYesPrice per unit (must be ≥ 0)
tax_typestringNonone, percentage, or fixed
tax_ratenumberNoTax value (e.g. 7.5 for 7.5%)
discount_typestringNonone, percentage, or fixed
discountnumberNoDiscount value
product_idstringNoOptional product reference UUID
Response: 
{
  "success": true,
  "data": {
    "id": "inv_01hx9ab2qr3st4uv5wx6kl",
    "invoice_number": "INV-0001",
    "title": "Web Design Services — November 2024",
    "status": "draft",
    "customer_name": "Amara Okafor",
    "customer_email": "amara@example.com",
    "currency": "NGN",
    "total_amount": "236250.00",
    "issue_date": "2024-11-01",
    "due_date": "2024-11-15",
    "created_at": "2024-11-01T11:00:00.000Z"
  }
}
Newly created invoices have status: "draft". The customer cannot pay until you send the invoice.

​
Add line items after creation

You can add additional line items to a draft invoice at any time before sending it: 
curl -X POST https://api.dubupay.com/api/v1/invoices/inv_01hx9ab2qr3st4uv5wx6kl/line-items \
  -H "X-Api-Key: dubu_sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "SEO optimisation",
    "quantity": 1,
    "unit_price": 50000,
    "discount_type": "percentage",
    "discount": 10
  }'

​
Remove a line item

cURL
curl -X DELETE \
  "https://api.dubupay.com/api/v1/invoices/inv_01hx9ab2qr3st4uv5wx6kl/line-items/li_01hx9bb2qr3st4uv5wx6mn" \
  -H "X-Api-Key: dubu_sk_live_your_api_key"

​
Send the invoice by email

Once you’re satisfied with the invoice, send it to the customer’s email address: 
curl -X POST \
  https://api.dubupay.com/api/v1/invoices/inv_01hx9ab2qr3st4uv5wx6kl/send \
  -H "X-Api-Key: dubu_sk_live_your_api_key"
Sending the invoice transitions its status from draft to pending. The customer receives an email with a payment link and a summary of all line items.

​
Update an invoice

You can update a draft or pending invoice. Once an invoice is paid or canceled, updates are not accepted. 
curl -X PATCH \
  https://api.dubupay.com/api/v1/invoices/inv_01hx9ab2qr3st4uv5wx6kl \
  -H "X-Api-Key: dubu_sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "due_date": "2024-11-22",
    "notes": "Extended deadline upon customer request."
  }'
Updatable fields: title, customer_name, customer_email, currency, issue_date, due_date, notes, status (to draft, pending, or canceled)

​
Delete an invoice

You can delete a draft invoice. Paid or canceled invoices cannot be deleted.
cURL
curl -X DELETE https://api.dubupay.com/api/v1/invoices/inv_01hx9ab2qr3st4uv5wx6kl \
  -H "X-Api-Key: dubu_sk_live_your_api_key"

​
List invoices

curl "https://api.dubupay.com/api/v1/invoices?status=pending&limit=20" \
  -H "X-Api-Key: dubu_sk_live_your_api_key"
Filter by status (draft, pending, paid, overdue, canceled) or search (matches customer name or email). Supports page and limit (max 100) for pagination.

​
Retrieve a single invoice

curl https://api.dubupay.com/api/v1/invoices/inv_01hx9ab2qr3st4uv5wx6kl \
  -H "X-Api-Key: dubu_sk_live_your_api_key"
To collect payment on an invoice without building a custom checkout UI, create a checkout link linked to the invoice ID. Dubu Pay hosts the payment page for you.