Customer / Debtors

Document metadata

Category: Customer
Endpoint: GET https://valora.spotahome.com/api/v1/c/debtors
Sandbox: GET https://valora-testing.laravel.cloud/api/sandbox/v1/c/debtors
Authentication: Bearer token (long-lived API token, auth:api guard)
Auth doc: /developers/auth/api-key-authentication
Token class: customer
Pagination: Supported
Filters: Supported
Version: 1
Stability: stable
Deprecated: No
Last updated: 2026-05-03

Debt Records

List outstanding and historical debt records for the authenticated customer account.

Shared conventions and base URLs live in Customer API Documentation.

API hosts:

Production https://valora.spotahome.com/ (sandbox compatible);

Staging / testing https://valora-testing.laravel.cloud/ (sandbox compatible).

Endpoint (production): GET https://valora.spotahome.com/api/v1/c/debtors Endpoint (sandbox): GET https://valora-testing.laravel.cloud/api/sandbox/v1/c/debtors

Authentication

Requirement	Details
Type	Bearer token (long-lived API token, `auth:api` guard)
How to obtain a token	See Long-Lived API Token Authentication
Header	`Authorization: Bearer {token}`
Accept	`Accept: application/json`
Token class	Customer only. Non-customer users receive HTTP 403 with message `Access denied. This resource is restricted to customers.` from `CheckCustomerApi` middleware.
Rate limit	120 requests per minute per authenticated customer.

Connection test

GET https://valora.spotahome.com/api/v1/c/debtors?test=connection
Authorization: Bearer {token}
Accept: application/json

Response: 200 OK

{
  "message": "You are connected!",
  "accepted_params": {
    "test": "Set to \"connection\" to test API connection",
    "search": "string, optional (booking reference or invoice number)",
    "status": "string, optional (pending|overdue|paid|settled|written_off|voided)",
    "debt_type": "string, optional (invoices_not_paid|transfers_badly_made|security_deposit_conflict|other)",
    "reference_id": "string, optional (exact booking or reference ID)",
    "due_date_from": "date (YYYY-MM-DD), optional",
    "due_date_to": "date (YYYY-MM-DD), optional",
    "amount_from": "decimal, optional (e.g., 100.50)",
    "amount_to": "decimal, optional (e.g., 500.00)",
    "page": "integer, optional (page number, default = 1)",
    "per_page": "integer, optional (items per page, default = 100, max = 500)"
  }
}

Query parameters

Parameter	Type	Required	Description
`test`	string	No	Set to `connection` to perform a connection test.
`search`	string	No	Search in `reference_id` and `invoice_number`.
`status`	string	No	Filter by debt status. See Debt statuses.
`debt_type`	string	No	Filter by debt type. See Debt types.
`reference_id`	string	No	Exact booking or reference ID.
`due_date_from`	date (YYYY-MM-DD)	No	Include records with due date on or after this date.
`due_date_to`	date (YYYY-MM-DD)	No	Include records with due date on or before this date.
`amount_from`	number	No	Minimum amount in major units (e.g. `100.50`). Stored internally in minor units.
`amount_to`	number	No	Maximum amount in major units.
`page`	integer	No	Page number. Default: `1`.
`per_page`	integer	No	Items per page. Default: `100`, max: `500`.

Success response

Status: 200 OK

{
  "message": "Debt records retrieved successfully.",
  "pagination": {
    "total": 2,
    "per_page": 100,
    "current_page": 1,
    "last_page": 1,
    "from": 1,
    "to": 2
  },
  "data": [
    {
      "id": "uuid-debt-123",
      "status": "pending",
      "reference_id": "BK123456",
      "amount": 50000,
      "currency": "EUR",
      "debt_type": "invoices_not_paid",
      "invoice_number": "INV-2025-001",
      "due_date": "2025-03-01",
      "payment_method": null,
      "settled_from": null,
      "original_amount": 50000,
      "final_amount": null,
      "paid_at": null,
      "written_off_at": null,
      "settled_on": null,
      "voided_at": null
    }
  ]
}

Debt record object

Field	Type	Description
`id`	string (UUID)	Debt record unique identifier.
`status`	string	Current status. See Debt statuses.
`reference_id`	string	Booking or reference identifier this debt is linked to.
`amount`	number	Current amount in minor units (cents).
`currency`	string	Currency code.
`debt_type`	string	Category of debt. See Debt types.
`invoice_number`	string \| null	Related invoice number, if applicable.
`due_date`	date \| null	Payment due date.
`payment_method`	string \| null	Payment method used when settled (e.g. `transfer`, `credit_card`).
`settled_from`	string \| null	Source reference when settled via a booking.
`original_amount`	number \| null	Original debt amount before any adjustments.
`final_amount`	number \| null	Final settled amount, if different from `original_amount`.
`paid_at`	string \| null	ISO 8601 timestamp when marked paid.
`written_off_at`	string \| null	ISO 8601 timestamp when written off.
`settled_on`	date \| null	Date settled.
`voided_at`	string \| null	ISO 8601 timestamp when voided.

Debt statuses

Status	Description
`pending`	Debt is open and awaiting payment.
`overdue`	Debt is past its due date.
`paid`	Debt has been paid in full.
`settled`	Debt has been settled (e.g. via a booking offset).
`written_off`	Debt has been written off.
`voided`	Debt record has been voided.

Debt types

Type	Description
`invoices_not_paid`	Invoice amount that was not collected.
`transfers_badly_made`	Erroneous transfer that created a debt.
`security_deposit_conflict`	Debt arising from a security deposit dispute.
`other`	Other debt type.

Errors

Status	Meaning
`404 Not Found`	No debt records matched the filters.

{
  "message": "No debt records found for the given filters.",
  "data": []
}

Notes

amount_from and amount_to accept major units; all amounts in the response are in minor units (cents).
Results are ordered by due_date descending (most recent first).
Some internal fields may not be included in the response for security purpose.
This endpoint shows all debt records regardless of status. Use ?status=pending or ?status=overdue to filter for actionable items only.