Customer / Conciliation By Booking

Document metadata

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

Conciliation by Booking

Returns a consolidated financial conciliation for a single booking reference, combining invoices, credit notes, penalties, debt, and completed transactions.

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

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/conciliation/booking
Authorization: Bearer {token}
Accept: application/json

Sending a request with no query parameters returns the accepted parameters payload.

Response: 200 OK

{
  "message": "You are connected!",
  "accepted_params": {
    "booking_id": "string, required (exact booking reference)"
  }
}

Query parameters

Parameter	Type	Required	Description
`booking_id`	string	Yes	Exact booking reference to conciliate.

Success response

Status: 200 OK

{
  "reference": "BK123456",
  "totals": {
    "transactions": 2,
    "transactions_made": 150000,
    "invoices_gross": 200000,
    "credit_notes_gross": 0,
    "penalties_gross": 3000,
    "debt": 1000
  },
  "invoicing": {
    "invoices": [
      {
        "document_id": "INV-2025-001",
        "doc_type": "Invoice",
        "invoice_to": "John Smith",
        "issue_date": "2025-01-10",
        "amount_net": 165000,
        "amount_gross": 200000,
        "currency": "EUR"
      }
    ],
    "credit_notes": []
  },
  "penalties": [
    {
      "id": "uuid-penalty-123",
      "booking_id": "BK123456",
      "status": "notify",
      "invoice_number": "PEN-2025-001",
      "amount": 3000,
      "currency": "EUR",
      "due_date": "2025-02-01"
    }
  ],
  "transactions": [
    {
      "booking_id": "BK123456",
      "beneficiary": "John Smith",
      "type": "Transfer",
      "amount": 150000,
      "issued_on": "2025-01-15",
      "currency": "EUR"
    }
  ]
}

Response fields

Top-level

Field	Type	Description
`reference`	string	The requested booking reference.
`totals`	object	Aggregated monetary totals for this booking.
`invoicing`	object	Grouped invoices and credit notes.
`penalties`	array	Penalty records associated with this booking.
`transactions`	array	Completed payment transactions for this booking.

`totals` object

Field	Type	Description
`transactions`	integer	Count of completed transactions.
`transactions_made`	integer	Sum of all transaction amounts in minor units (cents).
`invoices_gross`	integer	Total gross amount of invoices in minor units.
`credit_notes_gross`	integer	Total gross amount of credit notes in minor units.
`penalties_gross`	integer	Total of active (non-waived, non-pending) penalties in minor units.
`debt`	integer	Sum of pending debt records in minor units.

Errors

Status	Meaning
`422 Unprocessable Entity`	`booking_id` parameter is missing.
`404 Not Found`	No records exist for the given booking reference.

422 — missing booking_id:

{
  "message": "The booking_id parameter is required."
}

404 — no records found:

{
  "message": "No records found for this booking reference."
}

Notes

All monetary values are in minor units (cents).
Invoices in the response are scoped to the Landlord client type.
penalties_gross excludes penalties with status waived or pending.
debt reflects only records in pending status from the debtors table.