Waivers

Adds waiver templates and waiver submission fields to booking flows.

To use this capability, add octo/waivers to your Octo-Capabilities header.

This capability adds waiver definitions to products and adds waiver submission/status fields to booking write and booking response objects.

Routes

Product waiver fields are returned on:

• GET /products

• GET /products/{productId}

Booking waiver write fields are accepted on:

• POST /bookings

• PATCH /bookings/{uuid}

Waiver status fields are returned on booking objects and booking unit-item objects in booking responses.

Behaviour

• product.waiverPer determines where waiver inputs must be submitted.

• When waiverPer is BOOKING, submit waiver fields on the top-level booking request body.

• When waiverPer is UNIT, submit waiver fields on each unitItems[] object.

• waiver.content is markdown and can include field tags such as -First Name-=__ or -Email-=__("type":"email").

• Every field parsed from waiver.content is returned in waiver.fields[].

• You can render those fields inline in the waiver form content, or render them separately using waiver.fields[].

• inputType: "signature" should be rendered as a signature box.

• inputType: "country" should be rendered as a country dropdown.

• For country, submit the selected value as an ISO 3166-1 alpha-2 code (for example GB, US).

• Standard waiver submission requires waiverId and waiverFieldValues.

• waiverFile is optional and can be sent at booking level or unit-item level. Use a PDF data URI (data:application/pdf;base64,...) if you want to save a rendered waiver copy.

• If waiverId is sent at the wrong level, the API returns WAIVER_ON_BOOKING_ONLY or WAIVER_ON_TICKET_ONLY.

• waiverId must match one of product.waivers[]; otherwise the API returns INVALID_WAIVER_ID.

• waiverFieldValues must be an array and each record must include fieldId.

• waiversComplete indicates whether waiver requirements are complete for the booking/unit item.

Schema Additions (JSON)

These are additive fragments showing only fields introduced by this capability.

Product

{
  "// ...rest of product object": "...",
  "waiverPer": "UNIT",
  "waiverRequired": true,
  "waivers": [
    {
      "id": "6d8c49eb-d6d3-4f03-a242-6f5f95f4d56f",
      "title": "Participant Release and Assumption of Risk",
      "shortDescription": "Required before tour participation.",
      "content": "I acknowledge and accept the risks of participation.\n\n-First Name-=__\n-Email-=__(\"type\":\"email\")\n-Signature-=__(\"type\":\"signature\")\n-Country-=__(\"type\":\"country\")",
      "fields": [
        {
          "id": "first_name",
          "internalName": "First Name",
          "title": "First Name",
          "shortDescription": null,
          "required": true,
          "inputType": "text",
          "maxLength": null,
          "selectOptions": []
        },
        {
          "id": "email",
          "internalName": "Email",
          "title": "Email",
          "shortDescription": null,
          "required": true,
          "inputType": "email",
          "maxLength": null,
          "selectOptions": []
        },
        {
          "id": "signature",
          "internalName": "Signature",
          "title": "Signature",
          "shortDescription": null,
          "required": true,
          "inputType": "signature",
          "maxLength": null,
          "selectOptions": []
        },
        {
          "id": "country",
          "internalName": "Country",
          "title": "Country",
          "shortDescription": null,
          "required": true,
          "inputType": "country",
          "maxLength": null,
          "selectOptions": []
        }
      ]
    }
  ]
}

BookingWriteRequest

{
  "// ...rest of booking write request object": "...",
  "waiverId": "6d8c49eb-d6d3-4f03-a242-6f5f95f4d56f",
  "waiverFieldValues": [
    {
      "fieldId": "first_name",
      "value": "Jane"
    },
    {
      "fieldId": "email",
      "value": "[email protected]"
    },
    {
      "fieldId": "signature",
      "value": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    },
    {
      "fieldId": "country",
      "value": "US"
    }
  ]
}

BookingWriteRequest (Offline/In-Person)

{
  "// ...rest of booking write request object": "...",
  "waiverId": "6d8c49eb-d6d3-4f03-a242-6f5f95f4d56f",
  "waiverFieldValues": [
    {
      "fieldId": "first_name",
      "value": "Jane"
    },
    {
      "fieldId": "email",
      "value": "[email protected]"
    },
    {
      "fieldId": "signature",
      "value": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    },
    {
      "fieldId": "country",
      "value": "US"
    }
  ],
  "waiverFile": "data:application/pdf;base64,JVBERi0xLjQKJcTl8uXr..."
}

BookingUnitItemWriteRequest

{
  "// ...rest of booking unit item write request object": "...",
  "waiverId": "6d8c49eb-d6d3-4f03-a242-6f5f95f4d56f",
  "waiverFieldValues": [
    {
      "fieldId": "first_name",
      "value": "Jane"
    },
    {
      "fieldId": "email",
      "value": "[email protected]"
    },
    {
      "fieldId": "signature",
      "value": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    },
    {
      "fieldId": "country",
      "value": "US"
    }
  ],
  "waiverFile": "data:application/pdf;base64,JVBERi0xLjQKJcTl8uXr..."
}

Booking

{
  "// ...rest of booking object": "...",
  "waiverId": "6d8c49eb-d6d3-4f03-a242-6f5f95f4d56f",
  "waiverFileUrl": "https://api.ventrata.com/uploads/waivers/waiver_booking_10045.pdf",
  "waiverFieldValues": [
    {
      "fieldId": "first_name",
      "value": "Jane"
    },
    {
      "fieldId": "email",
      "value": "[email protected]"
    },
    {
      "fieldId": "signature",
      "value": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    },
    {
      "fieldId": "country",
      "value": "US"
    }
  ],
  "waiversComplete": true
}

BookingUnitItem

{
  "// ...rest of booking unit item object": "...",
  "waiverId": "6d8c49eb-d6d3-4f03-a242-6f5f95f4d56f",
  "waiverFileUrl": "https://api.ventrata.com/uploads/waivers/waiver_booking_10045.pdf",
  "waiverFieldValues": [
    {
      "fieldId": "first_name",
      "value": "Jane"
    },
    {
      "fieldId": "email",
      "value": "[email protected]"
    },
    {
      "fieldId": "signature",
      "value": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    },
    {
      "fieldId": "country",
      "value": "US"
    }
  ],
  "waiversComplete": true
}