Create and send invoices to your customers

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

Status	Meaning
`draft`	Created but not yet sent to the customer
`pending`	Sent; awaiting payment
`paid`	Payment confirmed
`overdue`	Past the due date with no payment
`canceled`	Voided; 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
      }
    ]
  }'

const response = await fetch("https://api.dubupay.com/api/v1/invoices", {
  method: "POST",
  headers: {
    "X-Api-Key": "dubu_sk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    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,
      },
    ],
  }),
});
const { data: invoice } = await response.json();

Request fields:

Field	Type	Required	Description
`title`	string	Yes	Invoice title (max 255 chars)
`customer_name`	string	Yes	Recipient’s display name
`customer_email`	string	Yes	Recipient’s email address
`customer_id`	string	No	Link to an existing Dubu customer record
`currency`	string	No	`NGN` or `USD`. Defaults to `NGN`
`issue_date`	string	No	ISO date string (e.g. `2024-11-01`)
`due_date`	string	No	ISO date string
`notes`	string	No	Freeform notes shown on the invoice (max 2000 chars)
`line_items`	array	Yes	At least one line item is required

Line item fields:

Field	Type	Required	Description
`description`	string	Yes	Item description (max 500 chars)
`quantity`	integer	Yes	Must be a positive integer
`unit_price`	number	Yes	Price per unit (must be ≥ 0)
`tax_type`	string	No	`none`, `percentage`, or `fixed`
`tax_rate`	number	No	Tax value (e.g. `7.5` for 7.5%)
`discount_type`	string	No	`none`, `percentage`, or `fixed`
`discount`	number	No	Discount value
`product_id`	string	No	Optional 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
  }'

const response = await fetch(
  "https://api.dubupay.com/api/v1/invoices/inv_01hx9ab2qr3st4uv5wx6kl/line-items",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "dubu_sk_live_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      description: "SEO optimisation",
      quantity: 1,
      unit_price: 50000,
      discount_type: "percentage",
      discount: 10,
    }),
  }
);
const { data: lineItem } = await response.json();

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"

const response = await fetch(
  "https://api.dubupay.com/api/v1/invoices/inv_01hx9ab2qr3st4uv5wx6kl/send",
  {
    method: "POST",
    headers: { "X-Api-Key": "dubu_sk_live_your_api_key" },
  }
);
const { data } = await response.json();

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."
  }'

const response = await fetch(
  "https://api.dubupay.com/api/v1/invoices/inv_01hx9ab2qr3st4uv5wx6kl",
  {
    method: "PATCH",
    headers: {
      "X-Api-Key": "dubu_sk_live_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      due_date: "2024-11-22",
      notes: "Extended deadline upon customer request.",
    }),
  }
);
const { data: updated } = await response.json();

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"

const params = new URLSearchParams({ status: "pending", limit: "20" });
const response = await fetch(
  `https://api.dubupay.com/api/v1/invoices?${params}`,
  {
    headers: { "X-Api-Key": "dubu_sk_live_your_api_key" },
  }
);
const { data } = await response.json();

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"

const response = await fetch(
  "https://api.dubupay.com/api/v1/invoices/inv_01hx9ab2qr3st4uv5wx6kl",
  {
    headers: { "X-Api-Key": "dubu_sk_live_your_api_key" },
  }
);
const { data: invoice } = await response.json();

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.

Get Started

Authentication

Core Concepts

Guides

Account & Security

Create and send invoices to your customers

Invoice statuses

Create an invoice

Add line items after creation

Remove a line item

Send the invoice by email

Update an invoice

Delete an invoice

List invoices

Retrieve a single invoice

​Invoice statuses

​Create an invoice

​Add line items after creation

​Remove a line item

​Send the invoice by email

​Update an invoice

​Delete an invoice

​List invoices

​Retrieve a single invoice

Invoice statuses

Create an invoice

Add line items after creation

Remove a line item

Send the invoice by email

Update an invoice

Delete an invoice

List invoices

Retrieve a single invoice