API Reference

Create custom Payments

Non-Reservation payments

In case you'd like to add a payment to our API, thats not bound to a reservation (like maintenance, deep cleans or restockings), this is what an API call to POST:/v2/payments may look like.

{
    // Required: Currency for all lines
    "currency": "GBP",
    "description": "Maintenance",
    // Required: Payed on date
    "date": "2021-05-17T14:53:09.643Z",
    // Required: Use a unique reference
    "uniqueRef": "83971782",
    // Optional: metadata as an object
    "metadata": { },
    // Required: Add at least 1 payment line
    "lines": [
        {
            // Optional: Referencing listings happens on a line level
            "listingId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
          	// Required: amount
            "amount": 1000,
            // Required: Each line may define a unique reference to the payment
            "uniqueRef": "maintenance",
            // Required: Description
            "description": "Repair Wifi",
          	// Optional: metadata
            "metadata": {}
        }
    ]
}

Reservation payments

Get a reservation

Call GET:/v2/reservations?uniqueRef=someref, where "someref" is the ID from your booking platform. You can also use GET:/v2/reservations?confirmationCode=somecode to fetch reservations by their confirmation codes. In return, you'll receive the reservation with its finalytic ID.

{
    "data": [
        {
            "id": "bf141803-63c1-48ad-b8cf-a4d2348e63a1",
            "status": "booked",
            "confirmationCode": "08EMXX",
            "uniqueRef": "12345789",
            "guests": 2,
            "nights": 4,
            "bookingPlatform": "direct",
            "bookedAt": "2020-07-16T15:19:18+00:00",
            "checkIn": "2023-05-01T13:00:00+00:00",
            "checkOut": "2023-05-05T09:00:00+00:00",
            "currency": "eur",
            "bookerName": null,
            "guestName": null,
            "listingId": "041d7495-c1d8-4b6d-b25f-b75492f17aa9",
            "listingConnection": {
                "id": "e958bf4a-7000-488b-b9a3-fc31547cf426",
                "name": null,
                "uniqueRef": "12345",
                "metadata": null
            }
        }
    ],
    "page": 1,
    "totalPages": 1,
    "results": 1,
    "totalResults": 1
}

Post a payment

Use the reservation ID to create a payment. This is what an API call to POST:/v2/payments may look like.

{
  // Required: Currency for all lines
  "currency": "GBP",
  "description": "Maintenance",
  // Required: Payed on date
  "date": "2021-05-17T14:53:09.643Z",
  // Required: Use a unique reference, e.g. the reservation ID
  "uniqueRef": "bf141803-63c1-48ad-b8cf-a4d2348e63a1",
  // Optional: metadata as an object
  "metadata": { },
  // Required: Add at least 1 payment line
  "lines": [
    {
        // Required: Referencing reservations happens on a line level
        "reservationId": "bf141803-63c1-48ad-b8cf-a4d2348e63a1",
        // Required: amount
        "amount": 1000,
        // Required: Each line may define a unique reference to the payment
        "uniqueRef": "maintenance",
        // Required: Type of line (e.g. accommodation, cleaningFee, otaFee, ...)
        "type": "accommodation",
        // Required: Description
        "description": "Accommodation"
    },
    {
        // Required: Referencing reservations happens on a line level
        "reservationId": "bf141803-63c1-48ad-b8cf-a4d2348e63a1",
        // Required: amount
        "amount": 80,
        // Required: Each line may define a unique reference to the payment
        "uniqueRef": "cleaning",
        // Required: Type of line (e.g. accommodation, cleaning_fee, ota_fee, ...)
        "type": "cleaning_fee",
        // Required: Description
        "description": "Cleaning"
    }
  ]
}