Invoices

Invoices are drafted, sent to customers, and paid via a checkout link. An invoice goes through a defined lifecycle: draft → sent → paid | cancelled.

Object

{
  "id": "uuid",
  "merchant_id": "uuid",
  "customer_id": "uuid",
  "invoice_number": "INV-000042",
  "title": "March Consulting Invoice",
  "description": null,
  "status": "draft",
  "amount": 200000000,
  "currency": "USDC",
  "due_date": "2026-04-15",
  "line_items": [
    { "description": "Consulting — March", "quantity": 1, "unit_price": 200000000, "total": 200000000 }
  ],
  "subtotal": 200000000,
  "tax_rate": 0,
  "tax_amount": 0,
  "recipient_note": null,
  "checkout_id": null,
  "paid_at": null,
  "paid_amount": null,
  "created_at": "2026-03-16T10:00:00Z",
  "updated_at": "2026-03-16T10:00:00Z"
}

Status values: draft | sent | paid | cancelled

---

Create Invoice

POST /v1/invoices

Body

Field	Type	Required	Description
title	string	✓	Invoice title
customer_id	uuid		Attach existing customer
customer_name	string		Inline customer name (required if no customer_id)
customer_email	string
customer_country	string		ISO 3166-1 alpha-3 (e.g. SGP, USA)
description	string		Extended description
currency	string		Default: USDC
line_items	array		Line items array. See below
amount	integer		Total amount in 6dp. Use instead of line_items for a simple fixed amount
due_date	string		ISO 8601 date YYYY-MM-DD
recipient_note	string		Note shown to the customer on the invoice
subtotal	integer		Pre-tax amount in 6dp. Triggers tax calculation
tax_rate	integer		Manual tax rate in basis points (0–10000). e.g. 1000 for 10%. Used with subtotal
merchant_id	uuid		Reseller only. Create this invoice on behalf of another merchant. See Reseller

Line item fields:

Field	Type	Required
description	string	✓
quantity	integer	✓
unit_price	integer	✓

Example

curl -X POST https://api-test.dpt.xyz/v1/invoices \
  -H "Authorization: Bearer dptb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "March Consulting Invoice",
    "customer_email": "[email protected]",
    "customer_name": "Acme Corp",
    "currency": "USDC",
    "due_date": "2026-04-15",
    "line_items": [
      { "description": "Consulting — March", "quantity": 1, "unit_price": 200000000 }
    ]
  }'

---

List Invoices

GET /v1/invoices

---

Get Invoice

GET /v1/invoices/{id}

---

Activate Invoice (Send to Customer)

Transitions from draft to sent and generates a hosted checkout link.

POST /v1/invoices/{id}/activate

Body (optional)

Field	Type	Description
success_url	string	Redirect URL after successful payment
cancel_url	string	Redirect URL on cancellation

Response 200

{
  "invoice": { /* Invoice object */ },
  "checkout": { /* Checkout object with hosted_url */ }
}

---

Cancel Invoice

DELETE /v1/invoices/{id}

Only draft or sent invoices can be cancelled. Returns 204 No Content.