Offers Packet

As we connect to different systems using a range of different languages, we can interpret several things as a true. Generally speaking holidaymaker will use a standard true/false JSON boolean, however we also read a lower case string and checked if they are "1", "true", "yes", or "on" to then create the positive boolean. Unless explicitly noted, all booleans are defaulted as false if the node doesn't exist.

{
  "optionOne": true,
  "optionTwo": false,
  "allTheseAreValidTrues" : [
    1, "1", true, "true", "on", "yes"
  ]
}

A category packet contains the ID to filter entities, and also the name to render. Typically they are sorted by their priority integer which defaults at 99 if not set. The lower this number the higher in the list. After priority they are alphabatised (case insensitive). An 'All' category is never required as the app surfaces create this. Holiday home sales categories also should include a banner image url, as they are also rendered as banners on the home sales section landing page.

{
  "id": 42,
  "name": "Caravans",
  "slug": "caravans",
  "priority": 5,
  "imgUrl": "https://link-to-homesales-caravans-banner.jpg?v=12345",
  "locales": [
    "cy" : "Name Translation"
  ]
}

id

Type : Integer - Required

Category ID used for filtering entities. This should be unique to the specific entity category, however does not need to be unique within scope of other entities and data.

name

Type : String - Required

Name of category which is rendered in various places in the app surfaces

slug

Type : String - Optional

Currently optional as unused by categories. Filtering uses IDs, but slug is stored to potentially be referenced by future

priority

Type : Integer - Optional

Defaults to 99 if not set. The lower the priority, the higher this category will be sorted before alphabetisation.

imgUrl

Type : Image Url String - Optional

Currently only used by holiday home sales categories. This image is used as the banner on the holiday homes sales section landing page.

locales

Type : Array of String - Optional

An array of localisable name translations for this category. This can include multiple translated names with the array should be keyed with the locale code which are supported by your holidaymaker install

This is string definition to define a type of code to be used. The three options available are :
• "none" - No code (default)
• "promo" - Text promo code
• "qr" - Rendered QR Code
• "barcode" - Rendered Code 128 Barcode

//Render a text promo code
{
  "codeType": "promo",
  "codeData": "20OFF",
}

//Render a QR code with textual data
{
  "codeType": "qr",
  "codeData": "PREFIX_OFFERCODE_DATA_FOR_A_POS",
}

//Render a Code 128 Barcode with textual data
{
  "codeType": "barcode",
  "codeData": "9780261103252",
}

When dealing with time, as well as dates, our data packets will typically use an epoch integer. Our date/times will normally be in UTC/GMT - unless it will be a renderable time to the end user, when it currently will use the 'Europe/London' timezone to take into account daylight savings time.

{
  "lastChange": 1691481892,
  "time": 1691398800,
  "endTime": 1691402400
}

Our app surfaces talk to an image engine on our infrastructure to process and resize images for different smart phone screen densities. Because of this the size of images are less relevant as they are delivered at optimum sizes anyway. However due to processing power and speed we do recommend that image urls are all 3000 pixels or below. The app surfaces will never need an image this large, so it gives you the option of still having a large quality image, but can be loaded in the apps and our infrastructure efficiently. We support both png, jpeg, and webp images. You can optionally include a '?v=' version integer so this can be used for versioning. If you do include this you can ensure images are reprocessed if the source image is changed on your servers.

{
  "imgUrl": "https://your-wordpress-site.com/wp-content/uploads/2023/08/a-large-image-3000x2100.jpg?v=1691481892",
  "image": "https://your-wordpress-site.com/wp-content/uploads/2023/08/a-smaller-image.png"
}

Standard JSON Integer - 0 is commonly considered to be a default value, unless it is an valid ID when -1 is used. For sort priorities 99 is used as the default.

{
  "key1": 9,
  "key2": 42,
  "arrayOfInts": [
    2,
    3,
    5,
    8
  ] 
}

A title and url of a link button. These are often attached to other entities to provide external links or pdf downloads such as onsite food menus, or more information about special offers.

{
  "url": "https:/your-wordpress-website.co.uk/wp-content/uploads/2021/08/offer-voucher.pdf",
  "title": "Download voucher"
}

url

Type : String - Required

Url to external link or pdf/doc attachment

title

Type : String - Required

Text for call to action button

This represents a single offer entity within the app. Most properties are optional, with some changing its visibility and behaviour, when others simple enhance its rich content.

For multipark installs the 'sites' property is required. If you wish the offer to appear for a park then you must include it's groupsite key in the sites array.

{
  "id": 9384,
  "title": "VIP Book Again Deal",
  "description": "Enjoy 10% off* your next Holiday stay in 2023 with offer code 'VIP10'",
  "copy": "Enjoy 10% off* your next Holiday stay in 2023 with offer code 'VIP10'.#BREAK##BREAK#Book during your current stay to enjoy this exclusive discount.#BREAK##BREAK#Simply quote your exclusive offer code 'VIP10' and receive 10% off* your next 2023 Holiday stay when re-booking on our website, or at our reservations team at reception."
  "priority": 1,
  "imgUrl": "https://your-wordpress-website.co.uk/wp-content/uploads/2021/03/vip-offer.jpg?v=1690208174",
  "location": 42,
  "gallery": [
    "https://your-wordpress-website.co.uk/wp-content/uploads/2021/03/offer1.jpg?v=1690208174",
    "https://your-wordpress-website.co.uk/wp-content/uploads/2021/03/offer2.jpg?v=1690208174",
    "https://your-wordpress-website.co.uk/wp-content/uploads/2021/03/offer3.jpg?v=1690208174"
  ],
  "onHolidayOnly": true,
  "signedInOnly": false,
  "isOwnersOnly": false,
  "startDate": 1690848000,
  "endDate": 1698624000,
  "accomodationTypes": [
    "caravans",
    "lodges",
    "touring"
  ],
  "ctaUrl": "https://toyourbookingengine.com/specialoffer",
  "ctaText": "Book Now"
  "smallPrint": "*Use code: VIP10. Offer applies to future bookings in 2023 made during current stay. Not transferable and cannot be exchanged for cash. Minimum spend £250, maximum discount amount £150, one voucher per booking. Cannot be used with other offer codes. Can be booked online or offline. Offer may be withdrawn at any time.",
  "duration": "Any number of nights",
  "fromPrice": "from £150",
  "codeType": "promo",
  "codeData": "VIP10",
  "linksHeading": "More information",
  "links": [
    {
      "url": "https:/your-wordpress-website.co.uk/wp-content/uploads/2021/08/offer-voucher.pdf",
      "title": "Download voucher",
      "type": "download"
    }
  ],
  "sites": [
    "park-one",
    "park-two"
  ],
  "categories": [
    87
  ]
}

id

Type : Integer - Required

ID for this offer. This needs to be unique to others offers in the list, however does not need to be unique to other entities. This ID should also not change between data requests/packets.

title

Type : String - Required

Offer title

description

Type : Rich Text / Multiline String - Optional

List description. This is rendered as a small amount of text on the offer cards within the app surfaces.

copy

Type : Rich Text / Multiline String - Optional

Larger amount of text for the detail section of the app surfaces offer section.

priority

Type : Integer - Optional

Defaults to 99 - the lower the priority the higher on the offer lists views it will be before alphabetisation.

imgUrl

Type : Image Url String - Optional

Landscape hero image used on the offer list views and detail view

location

Type : Integer - Optional

This is an optional ID number of a 'place' record. If this is set then the offer will be associated with that, and the app surfaces can cross link across to that place record. Example offer could be a discount at on park cafe, so you could add the ID of the cafe onsite place record.

gallery

Type : Array of Image Url String - Optional

A list of image urls to render as a swipable gallery in the offer detail. These are a landscape hero style ratio.

onHolidayOnly

Type : Boolean - Optional

If set to true this offer will only be visible to users who have logged in with a valid holiday booking, AND is between their arrival and departure date (inclusive) - Note that the holidaymaker CMS would normally only allow one of these three options to be set to true.

signedInOnly

Type : Boolean - Optional

If set to true this offer will only be visible to users who have logged in with a valid holiday booking - Note that the holidaymaker CMS would normally only allow one of these three options to be set to true.

isOwnersOnly

Type : Boolean - Optional

If set to true this offer will only be visible to users who have logged in as a home owner - Note that the holidaymaker CMS would normally only allow one of these three options to be set to true.

startDate

Type : Epoch Date/Time Integer - Optional

If this is optionally set, then the offer will be hidden in the app surfaces until this date/time

endDate

Type : Epoch Date/Time Integer - Optional

If this is optionally set, then the offer will render an expiry date and be hidden in the app surfaces after this date/time

accomodationTypes

Type : Array of Offer Accommodation Type - Optional

If an offer is for a holiday park and is relevant to booking another holiday then you can tag an offer as lodges, caravans, and touring/camping. These can be overridden to bespoke text/icons in the app surfaces, however the three tags in the data must remain the same

ctaUrl

Type : String - Optional

If a CTA url and text are provided then this single call to action button will be added under the hero image on an offer detail record. Additional external links and attachments can be added in the 'links' property

ctaText

Type : String - Optional

If a CTA url and text are provided then this single call to action button will be added under the hero image on an offer detail record. Additional external links and attachments can be added in the 'links' property

smallPrint

Type : Rich Text / Multiline String - Optional

The optional small print of the offer is rendered at the bottom of the detail record. It is common for holidaymaker clients to add the '*' symbol in their app descriptions.copy and then start this paragraph with '*'

duration

Type : String - Optional

This is rendered on both the offer list items and detail view as a subtitle. Traditionally used for the duration of a holiday park context offer eg '5 or 7 nights'

fromPrice

Type : String - Optional

This is rendered on both the offer list items and detail view as a subtitle. Traditionally used for the duration of a holiday park context offer eg 'starting from £150'

linksHeading

Type : String - Optional

This can optionally be set to override the heading above the additional links. If not set, and links are provided the default heading will be 'More information'

links

Type : Array of Link - Optional

An optional list of additional links or attachments. Examples on an offer may be further terms and conditions, a form to register for an offer, or a downloadable pdf voucher.

codeType

Type : Code Type - Optional

Choose to display/render a code of some kind on this offer. Choice of a text promo code, QR code, or a code 128 barcode

codeData

Type : String - Optional

Either the promo code, or string data for the QR Code / Barcode

sites

Type : Array of String - Required

Only required for multi site installs - can be disregarded for single park systems. This should be a list of valid groupsite keys which this offer should be available for. If this array is missing or empty then the offer will not render for any user.

categories

Type : Array of Integer - Optional

List of category IDs to associate with this offer. All offers will render in the 'All' tab, but this array can set which other category tabs the offer also appears in.

This is string definition to tag an offer to be relevant to accommodation types for a holiday park. The three options available are :
• "caravans"
• "lodges"
• "touring"
Note that these options are used, however they could relate to different overridden names/icons based on the specific holiday park setup.

{
  "accomodationTypes": [
    "caravans",
    "lodges",
    "touring"
  ],
}

Acts the same as the standard String type, however If text is assumed to include line breaks then we use a place holder of #BREAK#. These will then be replaced by the relevant line breaks depending on the language, and device that is rendering the text. This is commonly used in entity copy, and addresses. Rich text should not include HTML or other markup. There should always be a contextual consideration as well - for example if you copy includes a html anchor link to 'Read More' - then simply removing the markup will then leave the text 'Read More' which will be a redundant, none clickable piece of text within the app surfaces.

{
  "textWithBullets": "This paragraph will now have two line breaks, and then a list of bullets#BREAK##BREAK#• Bullet 1#BREAK#• Bullet 2#BREAK#• Bullet 3",
  "address": "Holidaymaker App Ltd#BREAK#Stowey House#BREAK#Bridport Road#BREAK#Dorchester#BREAK#DT12SB"
}

Standard JSON String - Often will have certain characters escaped depending what system is writing the JSON packet, however our parser only requires to have double quotes (") escaped. UTF-8 encoding is our standard, but others may be accepted if required. If line breaks are required in the text then the Rich Text / Multiline String type is used instead.

{
  "key1": "A string value",
  "key2": "Another string with an some \"quotes\" that need escaping",
  "arrayOfStrings": [
    "Item one as a string",
    "Item two as a string",
    "Item three as a string",
  ] 
}