# Waivers

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`

```json
{
  "// ...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`

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

### `BookingWriteRequest (Offline/In-Person)`

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

### `BookingUnitItemWriteRequest`

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

### `Booking`

```json
{
  "// ...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": "jane.doe@goldengatetours.com"
    },
    {
      "fieldId": "signature",
      "value": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    },
    {
      "fieldId": "country",
      "value": "US"
    }
  ],
  "waiversComplete": true
}
```

### `BookingUnitItem`

```json
{
  "// ...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": "jane.doe@goldengatetours.com"
    },
    {
      "fieldId": "signature",
      "value": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    },
    {
      "fieldId": "country",
      "value": "US"
    }
  ],
  "waiversComplete": true
}
```