Custom Fields

To support operational usage and marketing analytics for retailers, the API supports the transmission and storage of additional attributes. These attributes can be passed during the reservation confirmation process and are subsequently echoed back in booking and reservation responses.

Retailers often require specific custom fields to capture operational data such as project numbers, employee IDs, or cost centers. These fields are accepted in the /reservations/confirm request and can be named as preferred. They are passed as an array of objects within the custom_fields parameter. Currently, the system supports a maximum of 20 custom attributes and these fields are handled as key-value pairs.

Sample Request

 
...
    "custom_fields": [
        {
            "name": "project_id_test_test",
            "value": "1234123412341234"
        },
        {
            "name": "company_id",
            "value": "100"
        }
    ]
...

In the API response, the custom_fields are located within the relationships object.

Sample Response

 
{
  "data": {
    "type": "bookings",
    "id": "qeyXddMih-s7raA0voQbdg",
    "attributes": {
      ...
    },
    "relationships": {
      "custom_fields": {
        "data": {
          "project_id_test_test": "1234123412341234",
          "company_id": "100"
        }
      }
    }
  }
}

UK Rail Requirements

For UK Rail bookings, specific customer location data is required to correctly determine commission levels. This data is transmitted via the custom_fields array in the /reservations/confirm request.

Required Fields

To ensure accurate commission calculation, the following fields should be provided in the request:

• ip_based_location: The country code derived from the customer's IP address. Format should be ISO 3166-1 alpha-2 (e.g., GB, DE).
• payment_card_issuing_country: The country code where the customer's payment card was issued. Format should be ISO 3166-1 alpha-2 (e.g., GB, DE).

Commission Logic

The values provided in these fields directly impact the commission tier applied to the booking:

• Domestic Customer (Standard Commission): The system defaults to the domestic (lower) commission level if these fields are omitted. Additionally, if either ip_based_location OR payment_card_issuing_country is GB, the customer is treated as domestic.
• International Customer (Higher Commission): The higher commission level is applied only if both ip_based_location AND payment_card_issuing_country are provided and neither is GB.

Sample Request

 
{
    "reservation_id": "RHQ3H237",
    "title": "mr",
    "first_name": "Mary",
    "last_name": "Adams",
    "email": "mary.adams@email.com",
    "phone": "4877777777777",
    "city": "Berlin",
    "zip_code": "12345",
    "street_and_number": "Berlinstr. 00",
    "execute_payment": false,
    "payment_method": "demand_note",
    "terms_accepted": true,
    "send_customer_email": true,
    "passengers": [
        {
            "type": "PNOS",
            "first_name": "Mary",
            "last_name": "Adams",
            "birthdate": "1993-05-11",
            "gender": "F"
        }
    ],
    "custom_fields": [
        {
            "id": "URAI-GBLONLDM-GBBHXBIO-ip_based_location-GB",
            "name": "ip_based_location",
            "value": "GB"
        },
        {
            "id": "URAI-GBLONLDM-GBBHXBIO-payment_card_issuing_country-GB",
            "name": "payment_card_issuing_country",
            "value": "GB"
        }
    ]
}
}]