Invoices API — create and send payment invoices

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

Status	Description
`draft`	Invoice is being prepared and has not been sent.
`pending`	Invoice has been sent and is awaiting payment.
`paid`	Payment has been received.
`overdue`	The due date has passed without payment.
`canceled`	Invoice 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.

Show Line item fields

description

string

required

Line item description (e.g. product name or service detail). Maximum 500 characters.

quantity

number

required

Number of units. Must be a positive integer.

unit_price

number

required

Price per unit. Must be 0 or greater.

product_id

string

Optional UUID of a product in your catalog. Populates description and pricing from the product.

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.

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

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.

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

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.

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.

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.

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.

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.

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"

Overview

Auth

Payments

Trading

Commerce

Webhooks

Invoices API — create and send payment invoices

Invoice statuses

Create an invoice

Request body

Example

Invoice response fields

List invoices

Query parameters

Example

Get an invoice

Update an invoice

Delete an invoice

Send invoice by email

Add a line item

Remove a line item

​Invoice statuses

​Create an invoice

​Request body

​Example

​Invoice response fields

​List invoices

​Query parameters

​Example

​Get an invoice

​Update an invoice

​Delete an invoice

​Send invoice by email

​Add a line item

​Remove a line item

Invoice statuses

Create an invoice

Request body

Example

Invoice response fields

List invoices

Query parameters

Example

Get an invoice

Update an invoice

Delete an invoice

Send invoice by email

Add a line item

Remove a line item