Invoices API

The Invoices API provides access to invoice records, including line items, payment status, and related transactions.

Base URL

https://api.otesse.com/v1/invoices

List Invoices

GET /v1/invoices

Query Parameters

Parameter	Type	Description
status	string	draft, pending, paid, overdue, void
customer_id	string	Filter by customer
date_from	string (ISO 8601)	Invoice date range start
date_to	string (ISO 8601)	Invoice date range end
min_amount	integer	Minimum total (in cents)
max_amount	integer	Maximum total (in cents)
page	integer	Page number
per_page	integer	Items per page (max: 100)

Example Response

{
  "data": [
    {
      "id": "inv_01HQ3K5M7N",
      "number": "INV-2026-00142",
      "status": "paid",
      "customer": {
        "id": "cust_01HQ3K5M7N",
        "name": "John Smith"
      },
      "booking_id": "bk_01HQ3K5M7N8P9R",
      "line_items": [
        {
          "description": "Residential Cleaning — 3BR/2BA",
          "quantity": 1,
          "unit_price": 15000,
          "total": 15000
        },
        {
          "description": "Inside Oven Cleaning",
          "quantity": 1,
          "unit_price": 3500,
          "total": 3500
        }
      ],
      "subtotal": 18500,
      "discount": 3700,
      "discount_description": "Bi-weekly subscriber discount (20%)",
      "tax": 1258,
      "total": 16058,
      "amount_paid": 16058,
      "balance": 0,
      "issued_at": "2026-02-15T18:00:00Z",
      "paid_at": "2026-02-15T18:05:00Z",
      "payment_method": {
        "type": "card",
        "brand": "visa",
        "last4": "4242"
      }
    }
  ]
}

Get an Invoice

GET /v1/invoices/:id

Returns the full invoice with line items, payment details, and related booking reference.

Create an Invoice

POST /v1/invoices

{
  "customer_id": "cust_01HQ3K5M7N",
  "line_items": [
    {
      "description": "Custom consultation fee",
      "quantity": 1,
      "unit_price": 7500
    }
  ],
  "tax_rate": 8.5,
  "due_date": "2026-03-01",
  "send_email": true,
  "auto_charge": false
}

Void an Invoice

POST /v1/invoices/:id/void

{
  "reason": "Duplicate invoice"
}

Voiding sets the invoice status to void and releases any pending payment. If payment was already collected, use the refund endpoint instead.

Issue a Refund

POST /v1/invoices/:id/refund

{
  "amount": 5000,
  "reason": "Partial service — crew unable to complete kitchen",
  "refund_to": "original_payment_method"
}

Omit amount for a full refund. Partial refunds specify the amount in cents. The refundto field can be originalpaymentmethod or accountcredit.