Custom Reservation Fields Migration

Overview

This guide shows you how to upgrade from v2 to v3 custom reservation fields endpoints. The key changes are:

• Uses a new path - /reservations-v3/{reservationId}/custom-fields
• Changes the API response contract - includes an envelope with the reservationId and wraps the field under a customfields object with its own _id.
• Shapes do not match 1:1 - The API response contains additional fields in comparison to what is given by you.

Compatibility Notes

• The new API is fully compatible with reservations created using the old (v2) reservations resource (/reservations/)

Endpoint-by-Endpoint Migration

1. Get all populated custom fields for a reservation

Endpoint change

The path has changed from /reservations/ to /reservations-v3/

Response change

[
 {
   "fieldId": "637bad36eea326005171289c",
   "value": true
 },
 {
   "fieldId": "65d8828978f63800130b19ae",
   "value": "66ffa20dfe4ac4000f03d35d"
 }
]

{
 "reservationId": "673e3b1f4a6b5af4a0902ca5",
 "customFields": [
   {
     "value": true,
     "_id": "68f9fa360d5e34bd09f2ca91",
     "fieldId": "637bad36eea326005171289c"
   },
   {
     "value": "66ffa20dfe4ac4000f03d35d",
     "_id": "68f9fa360d5e34bd09f2ca92",
     "fieldId": "65d8828978f63800130b19ae"
   }
 ]
}

2. Get a specific custom field by ID for a reservation

Endpoint change

The path has changed from /reservations/ to /reservations-v3/.

Response change

The response adds the reservationId, and the field is now wrapped under customField and with its own object _id.

{
 "fieldId": "637bad36eea326005171289c",
 "value": true
}

{
 "reservationId": "673e3b1f4a6b5af4a0902ca5",
 "customField": {
   "value": true,
   "_id": "68f9fa360d5e34bd09f2ca91",
   "fieldId": "637bad36eea326005171289c"
 }
}

3. Update the custom fields of a reservation

Endpoint change

The path has changed from /reservations/ to /reservations-v3/.

Body params

Retains the same partial update semantics. Only the given fields and their values are updated.

{
  "fieldId": "{fieldId}"
  "value": {{value}} // "string", boolean, or number as preconfigured
}

Response example

The field is now wrapped under customField and includes the reservationId and an object _id.

[
  {
    "fieldId": "637bad36eea326005171289c",
    "value": false
  },
  {
    "fieldId": "65d8828978f63800130b19ae",
    "value": "66ffa20dfe4ac4000f03d35d"
  }
]

{
 "reservationId": "673e3b1f4a6b5af4a0902ca5",
 "customFields": [
   {
     "_id": "68fa04d25a573614e9bb3dac",
     "fieldId": "637bad36eea326005171289c",
     "value": false
   },
   {
     "value": "66ffa20dfe4ac4000f03d35d",
     "_id": "68f9fa360d5e34bd09f2ca92",
     "fieldId": "65d8828978f63800130b19ae"
   }
 ]
}

4. Delete a custom field from a reservation

Endpoint change

The path has changed from /reservations/ to /reservations-v3/.

Response change

The response adds the reservationId, and the field is now wrapped under customField with an object _id.

Old

New

[
 {
   "fieldId": "65d8828978f63800130b19ae",
   "value": "66ffa20dfe4ac4000f03d35d"
 }
]

{
"reservationId": "673e3b1f4a6b5af4a0902ca5",
"customFields": [
 {
   "_id": "68fa05b1a5f238c3f6b33836",
   "fieldId": "65d8828978f63800130b19ae",
   "value": "66ffa20dfe4ac4000f03d35d"
 }
]
}

Migration checklist

• Update paths: /reservations/... to /reservations-v3/...
• Adjust response parsing: The new endpoints return -
  • { reservationId, customFields: [ ... ] } or
  • { reservationId, customField: { ... } }
• Targeting fields:
  • Use fieldId in request bodies and URL parameters.
  • Optionally store the returned _id for internal reference or logging.

Deprecation schedule

To ensure uninterrupted service, you must update your integration to use the Custom Reservations Fields v3 resource before the hard deprecation on 16 March 2026.