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

string

required

Invoice title shown to the customer. Maximum 255 characters.

string

required

Full name of the customer being billed. Maximum 255 characters.

string

required

Email address of the customer. Used when sending the invoice by email.

string

Optional UUID of an existing customer in your account. Links the invoice to a saved customer record.

string

Invoice currency: NGN or USD. Defaults to your account currency.

string

Invoice issue date in ISO 8601 format (e.g. 2024-01-15). Defaults to today.

string

Payment due date in ISO 8601 format. Optional. When set, Dubu will mark the invoice as overdue after this date if unpaid.

string

Optional notes or payment instructions displayed on the invoice. Maximum 2,000 characters.

array

required

At least one line item is required.

Show Line item fields

string

required

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

number

required

Number of units. Must be a positive integer.

number

required

Price per unit. Must be 0 or greater.

string

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

string

none, percentage, or fixed.

number

Tax amount for this line item.

string

none, percentage, or fixed.

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.

string

Human-readable invoice number (e.g. INV-0001).

string

Invoice title.

string

Customer full name.

string

Customer email.

string

Invoice currency.

string

Current invoice status.

number

Total invoice amount including all taxes and discounts.

string

Invoice issue date.

string

Payment due date. null if not set.

string

ISO 8601 timestamp of when payment was received. null until paid.

array

Array of line item objects attached to this invoice.

List invoices

GET /invoices

Query parameters

string

Filter by status: draft, pending, paid, overdue, or canceled.

string

Search by customer name, email, or invoice number.

number

Page number (1-indexed).

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.

string

New invoice title.

string

Updated customer name.

string

Updated customer email.

string

NGN or USD.

string

Updated issue date.

string

Updated due date. Pass null to remove it.

string

Updated notes. Pass null to clear.

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.

string

required

Line item description. Maximum 500 characters.

number

required

Number of units.

number

required

Price per unit.

string

Optional product UUID. When provided, the description and pricing default to the product’s values.

string

none, percentage, or fixed.

number

Tax amount for this line item.

string

none, percentage, or fixed.

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.

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