Customer / Penalties

Document metadata

Category: Customer
Endpoint: GET https://valora.spotahome.com/api/v1/c/penalties
Sandbox: GET https://valora-testing.laravel.cloud/api/sandbox/v1/c/penalties
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

Penalties

List penalty 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/penalties Endpoint (sandbox): GET https://valora-testing.laravel.cloud/api/sandbox/v1/c/penalties

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/penalties?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|notify|paid|waived|settled)",
    "booking_id": "string, optional (exact booking reference)",
    "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 `booking_id` and `invoice_number`.
`status`	string	No	Filter by penalty status. See Penalty statuses.
`booking_id`	string	No	Exact booking reference.
`due_date_from`	date (YYYY-MM-DD)	No	Include penalties with due date on or after this date.
`due_date_to`	date (YYYY-MM-DD)	No	Include penalties 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": "Penalties retrieved successfully.",
  "pagination": {
    "total": 3,
    "per_page": 100,
    "current_page": 1,
    "last_page": 1,
    "from": 1,
    "to": 3
  },
  "data": [
    {
      "id": "uuid-penalty-123",
      "booking_id": "BK123456",
      "status": "notify",
      "invoice_number": "PEN-2025-001",
      "amount": 3000,
      "amount_eur": 3000,
      "rate_to_eur": "1.0000000000",
      "currency": "EUR",
      "due_date": "2025-02-01",
      "cancelled_on": null,
      "link_view": "https://...",
      "link_download": "https://...",
      "settled_booking": null,
      "original_booking_amount": null,
      "final_amount": null,
      "timestamp_notify": "2025-01-20T09:00:00.000000Z",
      "timestamp_paid": null,
      "timestamp_waived": null,
      "timestamp_settled": null
    }
  ]
}

Penalty object

Field	Type	Description
`id`	string (UUID)	Penalty unique identifier.
`booking_id`	string	Booking reference.
`status`	string	Current status. See Penalty statuses.
`invoice_number`	string \| null	Penalty invoice number.
`amount`	integer	Penalty amount in minor units (cents).
`amount_eur`	integer \| null	Amount converted to EUR in minor units.
`rate_to_eur`	string \| null	Exchange rate used for EUR conversion.
`currency`	string	Original currency code.
`due_date`	date \| null	Payment due date.
`cancelled_on`	date \| null	Date cancelled, if applicable.
`link_view`	string \| null	URL to view the penalty document.
`link_download`	string \| null	URL to download the penalty document.
`settled_booking`	string \| null	Reference of the booking used to settle this penalty.
`original_booking_amount`	integer \| null	Original booking amount at time of penalty (minor units).
`final_amount`	integer \| null	Final settled amount in minor units.
`timestamp_notify`	string \| null	ISO 8601 timestamp when notification was sent.
`timestamp_paid`	string \| null	ISO 8601 timestamp when marked paid.
`timestamp_waived`	string \| null	ISO 8601 timestamp when waived.
`timestamp_settled`	string \| null	ISO 8601 timestamp when settled.

Penalty statuses

Status	Description
`pending`	Penalty created; not yet notified.
`notify`	Notification sent to the customer.
`paid`	Penalty has been paid.
`waived`	Penalty has been waived.
`settled`	Penalty settled via an alternative arrangement.

Errors

Status	Meaning
`404 Not Found`	No penalties matched the filters.

{
  "message": "No penalties 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).
Internal fields (account_id, account_manager, client_tin, landlord_name, etc.) are not included in the response.