Invoices

Access your invoices. Requires the read token ability.

Invoice kinds

Kind	Description
`winner`	Winning bid invoice — the amount owed by the auction winner for a lot
`platform_fee`	Seller platform fee invoice
`subscription`	Subscription billing invoice
`deposit`	Bid registration deposit

GET /api/v1/invoices read ability

Returns a paginated list of the authenticated user's invoices.

Query parameters

Param	Type	Description
status	string	Filter: `draft`, `open`, `paid`, `voided`, `refunded`
kind	string	Filter: `winner`, `platform_fee`, `subscription`, `deposit`
per_page	integer	Default 15
page	integer	Default 1

Example

curl "https://bidyear.com/api/v1/invoices?status=open" \
  -H "Authorization: Bearer {token}"

Response 200

{
  "success": true,
  "data": [
    {
      "id": 88,
      "invoice_number": "INV-2026-00088",
      "kind": "winner",
      "status": "open",
      "amount_due": 42000.00,
      "amount_paid": 0.00,
      "currency": "usd",
      "due_at": "2026-07-20T00:00:00Z",
      "paid_at": null,
      "lot": { "id": 55, "title": "80 Acres — Jones County TX", "slug": "80-acres-jones-county-tx" },
      "created_at": "2026-07-12T14:01:00Z"
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "per_page": 15, "total": 1 }
}

GET /api/v1/invoices/{id} read ability

Returns invoice detail. The id can be the numeric ID or the invoice number string (e.g. INV-2026-00088). Returns 403 if the invoice does not belong to the authenticated user.

Response 200

{
  "success": true,
  "data": { ... same as list item above ... }
}

Error responses

HTTP	Cause
403	Invoice does not belong to the authenticated user
404	Invoice not found