> ## 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.

# Invoices API — create and send payment invoices

> Create itemized invoices, manage line items, send invoices to customers by email, and track payment status from draft through to paid or overdue.

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

<ParamField body="title" type="string" required>
  Invoice title shown to the customer. Maximum 255 characters.
</ParamField>

<ParamField body="customer_name" type="string" required>
  Full name of the customer being billed. Maximum 255 characters.
</ParamField>

<ParamField body="customer_email" type="string" required>
  Email address of the customer. Used when sending the invoice by email.
</ParamField>

<ParamField body="customer_id" type="string">
  Optional UUID of an existing customer in your account. Links the invoice to a saved customer record.
</ParamField>

<ParamField body="currency" type="string">
  Invoice currency: `NGN` or `USD`. Defaults to your account currency.
</ParamField>

<ParamField body="issue_date" type="string">
  Invoice issue date in ISO 8601 format (e.g. `2024-01-15`). Defaults to today.
</ParamField>

<ParamField body="due_date" type="string">
  Payment due date in ISO 8601 format. Optional. When set, Dubu will mark the invoice as `overdue` after this date if unpaid.
</ParamField>

<ParamField body="notes" type="string">
  Optional notes or payment instructions displayed on the invoice. Maximum 2,000 characters.
</ParamField>

<ParamField body="line_items" type="array" required>
  At least one line item is required.

  <Expandable title="Line item fields">
    <ParamField body="description" type="string" required>
      Line item description (e.g. product name or service detail). Maximum 500 characters.
    </ParamField>

    <ParamField body="quantity" type="number" required>
      Number of units. Must be a positive integer.
    </ParamField>

    <ParamField body="unit_price" type="number" required>
      Price per unit. Must be `0` or greater.
    </ParamField>

    <ParamField body="product_id" type="string">
      Optional UUID of a product in your catalog. Populates description and pricing from the product.
    </ParamField>

    <ParamField body="tax_type" type="string">
      `none`, `percentage`, or `fixed`.
    </ParamField>

    <ParamField body="tax_rate" type="number">
      Tax amount for this line item.
    </ParamField>

    <ParamField body="discount_type" type="string">
      `none`, `percentage`, or `fixed`.
    </ParamField>

    <ParamField body="discount" type="number">
      Discount amount for this line item.
    </ParamField>
  </Expandable>
</ParamField>

### Example

```bash theme={null}
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

<ResponseField name="id" type="string">
  Invoice UUID.
</ResponseField>

<ResponseField name="invoice_number" type="string">
  Human-readable invoice number (e.g. `INV-0001`).
</ResponseField>

<ResponseField name="title" type="string">
  Invoice title.
</ResponseField>

<ResponseField name="customer_name" type="string">
  Customer full name.
</ResponseField>

<ResponseField name="customer_email" type="string">
  Customer email.
</ResponseField>

<ResponseField name="currency" type="string">
  Invoice currency.
</ResponseField>

<ResponseField name="status" type="string">
  Current invoice status.
</ResponseField>

<ResponseField name="total_amount" type="number">
  Total invoice amount including all taxes and discounts.
</ResponseField>

<ResponseField name="issue_date" type="string">
  Invoice issue date.
</ResponseField>

<ResponseField name="due_date" type="string">
  Payment due date. `null` if not set.
</ResponseField>

<ResponseField name="paid_at" type="string">
  ISO 8601 timestamp of when payment was received. `null` until paid.
</ResponseField>

<ResponseField name="line_items" type="array">
  Array of line item objects attached to this invoice.
</ResponseField>

***

## List invoices

```
GET /invoices
```

### Query parameters

<ParamField query="status" type="string">
  Filter by status: `draft`, `pending`, `paid`, `overdue`, or `canceled`.
</ParamField>

<ParamField query="search" type="string">
  Search by customer name, email, or invoice number.
</ParamField>

<ParamField query="page" type="number">
  Page number (1-indexed).
</ParamField>

<ParamField query="limit" type="number">
  Results per page. Maximum `100`.
</ParamField>

### Example

```bash theme={null}
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
```

<ParamField path="id" type="string" required>
  UUID of the invoice to retrieve.
</ParamField>

```bash theme={null}
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.

<ParamField path="id" type="string" required>
  UUID of the invoice to update.
</ParamField>

<ParamField body="title" type="string">
  New invoice title.
</ParamField>

<ParamField body="customer_name" type="string">
  Updated customer name.
</ParamField>

<ParamField body="customer_email" type="string">
  Updated customer email.
</ParamField>

<ParamField body="currency" type="string">
  `NGN` or `USD`.
</ParamField>

<ParamField body="issue_date" type="string">
  Updated issue date.
</ParamField>

<ParamField body="due_date" type="string">
  Updated due date. Pass `null` to remove it.
</ParamField>

<ParamField body="notes" type="string">
  Updated notes. Pass `null` to clear.
</ParamField>

<ParamField body="status" type="string">
  Manually set status to `draft`, `pending`, or `canceled`.
</ParamField>

***

## Delete an invoice

```
DELETE /invoices/:id
```

Permanently deletes an invoice. You cannot delete invoices with `paid` status.

<ParamField path="id" type="string" required>
  UUID of the invoice to delete.
</ParamField>

```bash theme={null}
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`.

<ParamField path="id" type="string" required>
  UUID of the invoice to send.
</ParamField>

```bash theme={null}
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.

<ParamField path="id" type="string" required>
  UUID of the invoice.
</ParamField>

<ParamField body="description" type="string" required>
  Line item description. Maximum 500 characters.
</ParamField>

<ParamField body="quantity" type="number" required>
  Number of units.
</ParamField>

<ParamField body="unit_price" type="number" required>
  Price per unit.
</ParamField>

<ParamField body="product_id" type="string">
  Optional product UUID. When provided, the description and pricing default to the product's values.
</ParamField>

<ParamField body="tax_type" type="string">
  `none`, `percentage`, or `fixed`.
</ParamField>

<ParamField body="tax_rate" type="number">
  Tax amount for this line item.
</ParamField>

<ParamField body="discount_type" type="string">
  `none`, `percentage`, or `fixed`.
</ParamField>

<ParamField body="discount" type="number">
  Discount amount for this line item.
</ParamField>

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.

<ParamField path="id" type="string" required>
  UUID of the invoice.
</ParamField>

<ParamField path="lineItemId" type="string" required>
  UUID of the line item to remove.
</ParamField>

```bash theme={null}
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"
```