> For the complete documentation index, see [llms.txt](https://docs.zaui.com/webhooks/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zaui.com/webhooks/event-data-payloads/payload-versions.md).

# Payload Versions

Description of the Web hook payload versions

## Payload Versions

Zaui supports versioned webhook payloads so existing integrations can remain stable while newer integrations adopt an updated schema and additional data fields.

Each webhook can be configured to send a specific payload version. This allows existing consumers to remain on the legacy payload while new or updated integrations move to the modernized structure.

***

### Available Versions

#### `2016-04-10`

Legacy webhook payload format.

Use this version if your current integration depends on the original payload structure and formatting.

#### `2026-04-10`

Current webhook payload format.

Use this version for new integrations or when updating an existing integration to the modernized schema. This version introduces structural, type, and field-level changes, including pass-related payload support and additional booking, activity, and transaction attributes.

***

### How Version Selection Works

Webhook payload versioning is configured **per webhook record**.

When creating or editing a webhook in Zaui, you can choose which payload version that webhook should send:

* A webhook set to `2016-04-10` continues to receive the legacy payload shape.
* A webhook set to `2026-04-10` receives the updated payload shape and field set.

The delivered payload includes `eventNotificationApiVersion`, which identifies the version used for that webhook event.

***

### Which Version Should I Use?

Use `2026-04-10` for all new integrations.

If you already consume Zaui webhooks in production and your parser depends on the legacy structure, remain on `2016-04-10` until you have tested and updated your integration for the new schema.

***

### What Changed in `2026-04-10`

The `2026-04-10` payload modernizes the webhook schema in several important ways:

* collections are emitted as JSON arrays
* numeric fields are emitted as native numbers
* boolean fields are emitted as native booleans
* date-time fields use ISO 8601 with timezone offset
* missing scalar values use `null`
* additional booking, activity, and transaction fields are included
* pass sales and pass usage data are supported

These changes improve consistency, reduce parsing complexity, and make the payload easier to consume in modern systems.

***

### Key Differences Between Versions

#### Collections

Legacy payloads may wrap collections as objects. The modern payload uses arrays consistently.

Legacy:

```json
"customers": {
  "customer": {
    "customerId": "1614"
  }
}
```

Current:

```
"customers": [
  {
    "customerId": 93
  }
]
```

This same pattern applies to sections such as `activities`, `products`, `giftCertificates`, and `transactions`.

#### Numbers

Legacy payloads often emit numeric values as strings. The modern payload emits native numbers.

Legacy:

```
"eventNotificationTypeId": "100",
"amount": "42.900000"
```

Current:

```
"eventNotificationTypeId": 100,
"amount": 7840
```

#### Booleans

Legacy payloads may emit booleans as strings. The modern payload emits booleans directly.

Legacy:

```
"isBookingCancelled": "false"
```

Current:

```
"isBookingCancelled": false
```

#### Date and Time Formatting

Legacy payloads use mixed and inconsistent date formats. The modern payload uses ISO 8601 with timezone offset.

Legacy:

```
"eventNotificationDateTime": "2026-02-16 13:13:08",
"activityDate": "Thursday February 19 2026"
```

Current:

```
"eventNotificationDateTime": "2026-04-10T14:16:59-07:00",
"activityDate": "2026-04-09T00:00:00-07:00"
```

#### Null and Empty Values

Legacy payloads may use empty objects or empty strings inconsistently. The modern payload uses `null` for missing scalar values where appropriate.

Legacy:

```
"addressLine1": {},
"activityNotes": {}
```

Current:

```
"addressLine1": null,
"activityNotes": null
```

***

### Event Envelope

The event envelope in `2026-04-10` includes standard event metadata plus the selected payload version.

#### Example

```
{
  "eventNotificationUniqueId": "evt_5d64823a3422fe2d7cecf93d5818526743efeb18",
  "eventNotificationCompanyName": "Aurorasky ",
  "eventNotificationCompanyIdentifier": "b6589fc6ab",
  "eventNotificationGroupId": 100,
  "eventNotificationTypeId": 100,
  "eventNotificationType": "booking.creation",
  "eventNotificationDateTime": "2026-04-10T14:16:59-07:00",
  "eventNotificationName": "Booking Test",
  "eventNotificationSystem": "suppliertestsystem",
  "eventNotificationSystemUrl": "https://suppliertestsystem.zaui.net/",
  "eventNotificationApiVersion": "2026-04-10",
  "eventNotificationTypeV2": "booking.creation"
}
```

#### Notable Envelope Fields

| Field                         | Description                               |
| ----------------------------- | ----------------------------------------- |
| `eventNotificationGroupId`    | Event group identifier                    |
| `eventNotificationTypeId`     | Event type identifier                     |
| `eventNotificationType`       | Event name                                |
| `eventNotificationTypeV2`     | Normalized event type string              |
| `eventNotificationDateTime`   | Timestamp of the event in ISO 8601 format |
| `eventNotificationApiVersion` | Payload version selected on the webhook   |
| `eventNotificationName`       | Webhook name                              |
| `eventNotificationSystem`     | Source system name                        |
| `eventNotificationSystemUrl`  | Source system URL                         |

***

### Booking Object

The `booking` object in `2026-04-10` includes both structural improvements and additional fields.

#### Example

```
"booking": {
  "bookingId": 693,
  "isBookingCancelled": false,
  "bookingReference": "XKZFSBR",
  "bookingSaleDateTime": "2026-04-09T13:11:20-07:00",
  "bookingCloseDateTime": "2026-04-09T00:00:00-07:00",
  "bookingRef": "XKZFSBR",
  "agentRef": null
}
```

#### Booking Fields

| Field                  | Description                                            |
| ---------------------- | ------------------------------------------------------ |
| `bookingId`            | Booking identifier                                     |
| `isBookingCancelled`   | Indicates whether the booking is cancelled             |
| `bookingReference`     | Booking reference value emitted in the current payload |
| `bookingRef`           | Customer-facing booking reference                      |
| `agentRef`             | Optional reseller-supplied reference                   |
| `bookingSaleDateTime`  | Booking sale date and time                             |
| `bookingCloseDateTime` | Booking close date and time                            |

#### Notes

* `agentRef` is populated from `tbooking.referenceId` for agent/OTA bookings. For direct bookings (or when `referenceId` is not present), the value is `null`.
* Both `bookingReference` and `bookingRef` may be present in the current payload.

***

### Booking Revenue

The `bookingRevenue` structure in `2026-04-10` uses native numeric values.

#### Example

```
"bookingRevenue": {
  "bookingSubTotal": 6000,
  "bookingTax": 1839,
  "bookingTotal": 7840
}
```

Consumers should treat these values as numbers, not strings.

***

### Customer Data

Customer records are emitted as array items in the current version and use typed values consistently.

#### Example

```
"customers": [
  {
    "customerId": 93,
    "firstName": "Nad",
    "lastName": "Dau",
    "birthDate": "2006-02-23",
    "homePhone": null,
    "mobilePhone": "6404563125",
    "email": "nad.mel.dau@gmail.com",
    "addressLine1": null,
    "addressLine2": null,
    "city": null,
    "state": null,
    "zipCode": null,
    "country": "Canada",
    "username": "nad.mel.dau@gmail.com",
    "newsLetterOptIn": false,
    "loyaltyProgramOptIn": false,
    "allowsPrivateDataSharing": false
  }
]
```

***

### Activity Object

In `2026-04-10`, activity payloads include modernized typing as well as additional contextual fields.

#### Example

```
{
  "activityId": 2,
  "activityType": "Regular",
  "activityName": "The Rings of Saturn",
  "activityDate": "2026-04-09T00:00:00-07:00",
  "activityTime": "09:00:00",
  "activityDescription": "Fun facts about Saturn...",
  "activityDuration": "5:00:00"
}
```

#### Activity Fields

| Field                 | Description                                          |
| --------------------- | ---------------------------------------------------- |
| `activityId`          | Activity identifier                                  |
| `activityType`        | Activity type                                        |
| `activityName`        | Activity name                                        |
| `activityDate`        | Activity date in ISO 8601 format                     |
| `activityTime`        | Activity time                                        |
| `activityDescription` | Descriptive context for the booked activity instance |
| `activityDuration`    | Duration of the activity in `HH:MM:SS` format        |

#### Notes

For point-to-point activities, `activityDescription` may represent the actual passenger journey segment rather than the full route.

For point-to-point activities, `activityDuration` may reflect the time between departure and arrival stops.

***

### Transaction Object

The `transactions` array in `2026-04-10` contains modernized transaction records and supports pass usage data.

#### Example

```
{
  "id": 830,
  "attributeId": 830,
  "purchaseType": 3000,
  "transactionType": 2042,
  "transactionName": "Pass",
  "transactionTypeLedgerEntry": "N/A",
  "amount": 7840,
  "dateCreated": "2026-04-09T13:11:20-07:00",
  "productId": 0,
  "productDate": null,
  "activityId": 0,
  "activityDateTime": null,
  "resellerCompanyId": 0,
  "resellerCompanyName": null,
  "resellerInvoiceNumber": null,
  "resellerRateName": null,
  "resellerRate": 0,
  "resellerNet": 0,
  "discountRate": 0,
  "promoCodeName": null,
  "promoCodeRate": 0,
  "promoCodeRateType": null,
  "resellerBusinessNumber": null
}
```

#### Transaction Fields

| Field                        | Description                              |
| ---------------------------- | ---------------------------------------- |
| `id`                         | Transaction identifier                   |
| `attributeId`                | Transaction attribute identifier         |
| `purchaseType`               | Purchase type identifier                 |
| `transactionType`            | Transaction type identifier              |
| `transactionName`            | Transaction type name                    |
| `transactionTypeLedgerEntry` | Ledger entry classification              |
| `amount`                     | Transaction amount                       |
| `dateCreated`                | Transaction creation timestamp           |
| `productId`                  | Related product identifier               |
| `productDate`                | Related product date                     |
| `activityId`                 | Related activity identifier              |
| `activityDateTime`           | Related activity date-time               |
| `resellerCompanyId`          | Reseller company identifier              |
| `resellerCompanyName`        | Reseller company name                    |
| `resellerInvoiceNumber`      | Reseller invoice number                  |
| `resellerRateName`           | Reseller rate name                       |
| `resellerRate`               | Reseller rate value                      |
| `resellerNet`                | Reseller net value                       |
| `discountRate`               | Discount rate                            |
| `promoCodeName`              | Promo code name                          |
| `promoCodeRate`              | Promo code rate                          |
| `promoCodeRateType`          | Promo code rate type                     |
| `resellerBusinessNumber`     | Reseller business number                 |
| `passUsage`                  | Nested pass usage object when applicable |

#### Important Note

Do not assume `transactionReference` and `merchantRef` are currently available in `2026-04-10`.

For standard payment transactions (for example, credit card and cash payments), both `lineItemId` and `packageId` are returned as `null`. These fields are only populated where item-level transaction context applies.

Earlier source material identified them as planned, and the validated live payload used for documentation does not include them. Until explicitly confirmed in a live implementation, integrations should not treat them as guaranteed fields.

***

### Pass Data

The `2026-04-10` payload supports pass-related information for bookings and transactions.

#### Top-Level Pass Support

The booking payload can include:

* `passes`
* pass-related transaction information
* pass usage details on relevant transactions

#### Example Empty State

```
"passes": []
```

When a booking includes pass sales, the `passes` array may contain pass details such as pass metadata, pricing, validity, and usage-related values.

***

### Pass Usage on Transactions

In the current live `2026-04-10` implementation, pass usage is represented as a nested `passUsage` object on the transaction.

#### Example

```
"passUsage": {
  "passId": 7,
  "redemptionCode": "XK856LY",
  "usageType": "1",
  "unitsUsed": 1,
  "passName": "5 Trips",
  "passBalanceRemaining": 0,
  "transactionId": 830,
  "itemType": "activity",
  "itemId": 2,
  "itemName": "The Rings of Saturn",
  "amount": 7840,
  "redeemedOn": "2026-04-09T13:11:20-07:00"
}
```

#### Pass Usage Fields

| Field                  | Description                           |
| ---------------------- | ------------------------------------- |
| `passId`               | Pass identifier                       |
| `redemptionCode`       | Pass redemption code                  |
| `usageType`            | Pass usage type                       |
| `unitsUsed`            | Amount of pass value or units used    |
| `passName`             | Pass name                             |
| `passBalanceRemaining` | Remaining balance after redemption    |
| `transactionId`        | Related transaction identifier        |
| `itemType`             | Redeemed item type                    |
| `itemId`               | Redeemed item identifier              |
| `itemName`             | Redeemed item name                    |
| `amount`               | Amount associated with the redemption |
| `redeemedOn`           | Redemption timestamp                  |

***

### Breaking Changes to Consider Before Migrating

Switching a webhook from `2016-04-10` to `2026-04-10` may require parser changes.

Before switching versions, confirm that your integration can handle:

* arrays instead of object-wrapped collections
* numbers instead of numeric strings
* booleans instead of string booleans
* ISO 8601 date-time values with timezone offsets
* `null` values for optional scalar fields
* additional booking, activity, and transaction fields
* pass-related payload sections when applicable

***

### Migration Checklist

Before enabling `2026-04-10` on an existing webhook:

1. Update your parser to support array-based collections.
2. Update type handling for numbers and booleans.
3. Update date parsing for ISO 8601 with timezone offsets.
4. Update null-handling for optional values.
5. Validate any reconciliation logic that depends on transaction fields.
6. Test pass purchases and pass redemptions if your implementation uses passes.
7. Review the live payload output in a test environment before switching production endpoints.

***

### Recommended Best Practice

For new webhook integrations, use `2026-04-10`.

For existing consumers of the legacy webhook format, migrate only after validating payload parsing and downstream processing against the modernized schema.

***

### FAQ

#### What should the API Version field be set to?

Use `2026-04-10` for new integrations. Keep `2016-04-10` only for backward compatibility where an existing parser still depends on the legacy schema.

#### Is the version configured globally?

No. Versioning is selected per webhook record.

#### Does `2026-04-10` include pass-related data?

Yes. The current payload supports pass data and nested `passUsage` on transactions where applicable.

#### Are `transactionReference` and `merchantRef` available in `2026-04-10`?

Do not assume they are currently available. They are not present in the validated live example used for this documentation.

#### Where should the API Version help link in the UI point?

It should point to this page: `/webhooks/payload-versions`