> For the complete documentation index, see [llms.txt](https://developer.ivvy.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.ivvy.com/venues/getoraddbookingdata/add-or-update-booking.md).

# Add or Update Booking

<mark style="color:green;">`POST`</mark> `[PlatformAddress]/api/1.0/venue?action=addOrUpdateBooking`

Adds or updates the details of a venue booking. NOTE: The venue must have access to

*normal bookings*

in order to call this api action.

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "success": true,
  "id": 1234,
  "warnings": ["packageErrors", "packageSessionErrors"]
}
```

{% endtab %}

{% tab title="400 " %}

```javascript
{
  "errorCode": 400,
  "message": "The request contains invalid data",
  "specificCode": 24297,
  "additionalMessages": [
    "dateEventEnd: End date has to be greater than the start date."
  ]
}
```

{% endtab %}

{% tab title="429 " %}

```javascript
{
  "errorCode": 429
  "message": "Race condition error",
  "specificCode": 24299,
  "additionalMessages": []
}
```

{% endtab %}

{% tab title="500 " %}

```javascript
{
  "errorCode": 500,
  "message": "An error has occurred",
  "specificCode": 24296,
  "additionalMessages": []
}
```

{% endtab %}
{% endtabs %}

### Booking

| Property                          | Type                                                     | Required | Description                                                                                                                                                                                                                                                                                                                                    |
| --------------------------------- | -------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                                | integer                                                  | optional | The unique id of the booking to update. A new booking will be created if this parameter is not present.                                                                                                                                                                                                                                        |
| venueId                           | integer                                                  | required | The unique id of the venue to which the booking belongs.                                                                                                                                                                                                                                                                                       |
| leadId                            | integer                                                  | optional | The unique id of the opportunity to which the new booking will be assigned. Has no effect when updating a booking (i.e. an existing booking cannot be assigned to another opportunity).                                                                                                                                                        |
| bookingType                       | [Booking Type](#booking-type)                            | optional | The type of booking. Required when adding a new booking. Has no effect when updating a booking (i.e the type of an existing booking cannot be changed).                                                                                                                                                                                        |
| currentStatus                     | [Booking Status](#booking-status)                        | optional | The current status of the booking. Required when adding a new booking. Has no effect when updating a booking (i.e. the status of an existing booking cannot be changed). For example, to add a quote, the value should be 1.                                                                                                                   |
| code                              | string                                                   | optional | The unique reference code of the booking. Excluding this parameter from the request when adding a booking will cause the system to generate the code. The venue can be configured to prevent the code of an existing booking from being changed.                                                                                               |
| name                              | string                                                   | optional | The booking name. Required when adding a new booking.                                                                                                                                                                                                                                                                                          |
| companyId                         | integer                                                  | optional | The unique id of the company to assign to the booking. See [assigning a company/contact to the booking](#assigning-a-company-contact-to-the-booking).                                                                                                                                                                                          |
| company                           | object                                                   | optional | The data array of company. See addOrUpdateCompany API in contact namespace for parameters.                                                                                                                                                                                                                                                     |
| contactId                         | integer                                                  | optional | The unique id of the contact to assign to the booking See [assigning a company/contact to the booking](#assigning-a-company-contact-to-the-booking).                                                                                                                                                                                           |
| contact                           | object                                                   | optional | The data array of contact. See addOrUpdateContact API in contact namespace for parameters.                                                                                                                                                                                                                                                     |
| industryId                        | integer                                                  | optional | The unique id of the industry to which the *contact* belongs when a *contact* is [assigned to the booking](#assigning-a-company-contact-to-the-booking).                                                                                                                                                                                       |
| purchaseOrderNumber               | string                                                   | optional | The purchase order number of the booking.                                                                                                                                                                                                                                                                                                      |
| eventTypeId                       | integer                                                  | optional | The unique id of the booking event type. Required when adding a booking.                                                                                                                                                                                                                                                                       |
| eventSubTypeId                    | integer                                                  | optional | The unique id of the booking event sub type. Required when event type have sub types .                                                                                                                                                                                                                                                         |
| bookedById                        | integer                                                  | optional | The unique id of the account user who is the coordinator of the booking. Omit to add or update the booking without a coordinator, or set to null to remove the coordinator. See [Booking coordinator](#booking-coordinator).                                                                                                                   |
| canBeMoved                        | boolean                                                  | optional | Whether or not the dates of the booking are flexible, and the booking itself can be moved to other dates.                                                                                                                                                                                                                                      |
| dateEventStart                    | date                                                     | optional | The event start date of the booking. Required when adding a booking that includes event details. Has no effect if the venue doesn't have function space.                                                                                                                                                                                       |
| dateEventEnd                      | date                                                     | optional | The event end date of the booking. Required when adding a booking that includes event details. Has no effect if the venue doesn't have function space. When [adding a booking with an event template](#adding-an-event-template-to-a-new-booking), the end date cannot be more than 7 days after *dateEventStart*.                             |
| totalAttendees                    | integer                                                  | optional | The booking number of attendees. Required when adding a new booking. Has no effect when updating a booking (i.e. the number of attendees on a booking cannot be changed). When [adding a booking with an event template](#adding-an-event-template-to-a-new-booking), this number is assigned to the event template added to the booking.      |
| packageId                         | integer                                                  | optional | The unique id of the event template that will be added to all event days (i.e. dateEventStart to dateEventEnd) of the *new* booking. Has no effect when updating a booking (i.e. this cannot be used to change the event templates on a booking). See [adding an event template to a new booking](#adding-an-event-template-to-a-new-booking). |
| packagePrice                      | float                                                    | optional | The price of the event template added to the new booking. Has no effect when updating a booking. Excluding this parameter from the request will cause the system to use the price assigned to the event template by the venue. The value is rounded to 3 decimal places.                                                                       |
| isAccommIncluded                  | boolean                                                  | optional | Whether or not the booking includes accommodation. Has no effect if the venue doesn't have accommodation. Always true for *accommodation only* bookings.                                                                                                                                                                                       |
| dateAccomStart                    | date                                                     | optional | The earliest arrival date of the accommodation blocks on the booking. Required when adding a booking that includes accommodation. Has no effect if the venue doesn't have accommodation.                                                                                                                                                       |
| dateAccomEnd                      | date                                                     | optional | The latest departure date of the accommodation blocks on the booking. Required when adding a booking that includes accommodation. Has no effect if the venue doesn't have accommodation.                                                                                                                                                       |
| accommCutOffDate                  | date                                                     | optional | The cut off date for changes to the accommodation blocks on the booking. Only applies when the booking includes accommodation.                                                                                                                                                                                                                 |
| accommCancellationDate            | date                                                     | optional | The date before which the accommodation blocks on the booking can be cancelled. Only applies when the booking includes accommodation.                                                                                                                                                                                                          |
| accommChargingMethod              | [Charging Method](#accommodation-charging-methods)       | optional | The method used to charge for the accommodation blocks on the booking. Only applies when the booking includes accommodation.                                                                                                                                                                                                                   |
| accommGuaranteeRequired           | boolean                                                  | optional | Whether or not a guarantee is required for the accommodation blocks on the booking. Only applies when the booking includes accommodation.                                                                                                                                                                                                      |
| accommExternalBlockId             | string                                                   | optional | The block id from an external pms (property management system). Only applies when the booking includes accommodation.                                                                                                                                                                                                                          |
| accommReservationMethod           | [Reservation Method](#accommodation-reservation-methods) | optional | The method by which attendees will reserve rooms from the accommodation blocks on the booking. Only applies when the booking includes accommodation.                                                                                                                                                                                           |
| accommReservationCancellationDate | date                                                     | optional | The date after which reservations from the accommodation blocks cannot be cancelled. Only applies when the booking includes accommodation.                                                                                                                                                                                                     |
| accommArrivalMethod               | [Arrival Method](#accommodation-arrival-methods)         | optional | The method by which the group attendees will arrive at the venue. Only applies when the booking includes accommodation.                                                                                                                                                                                                                        |
| isConfidential                    | boolean                                                  | optional | Whether or not the booking is confidential. Only applies when the venue's account has access to confidential meetings.                                                                                                                                                                                                                         |
| otaFolioRef                       | string                                                   | optional | The Folio ID from the external postings extension installed by the venue.                                                                                                                                                                                                                                                                      |
| bookingRoleUserId1                | string                                                   | optional | The unique id of the account user assigned to the booking role label 1                                                                                                                                                                                                                                                                         |
| bookingRoleUserId2                | string                                                   | optional | The unique id of the account user assigned to the booking role label 2                                                                                                                                                                                                                                                                         |
| bookingRoleUserId3                | string                                                   | optional | The unique id of the account user assigned to the booking role label 3                                                                                                                                                                                                                                                                         |
| bookingRoleUserId4                | string                                                   | optional | The unique id of the account user assigned to the booking role label 4                                                                                                                                                                                                                                                                         |
| bookingRoleUserId5                | string                                                   | optional | The unique id of the account user assigned to the booking role label 5                                                                                                                                                                                                                                                                         |
| customFields                      | array of [Custom Field](#custom-field)                   | optional | The custom field values of the booking. A custom field value might be required depending on how it has been configured in the venue's account.                                                                                                                                                                                                 |
| discountCode                      | string                                                   | optional | The discount code applied to the booking. Send null to remove the discount from the booking.                                                                                                                                                                                                                                                   |
| isFromExternalSource              | boolean                                                  | optional | Whether an external system (e.g. a booking engine) is creating the booking on behalf of a customer. Only used when adding a booking, and ignored when updating one, so it cannot be changed later. Defaults to false. See [discounts on bookings from an external source](#discounts-on-bookings-from-an-external-source).                     |
| externalUrls                      | array of [ExternalUrl](#external-url-field) Field        | optional | This is an array of External URL field objects of the booking (a maximum of 3 objects allowed). When set to null, it will remove all externalUrls from the booking.                                                                                                                                                                            |

### Booking Type

The following booking types are supported when adding a new booking.

| Value | Description                                                                                                                    |
| ----- | ------------------------------------------------------------------------------------------------------------------------------ |
| 1     | A detailed booking that can include both event templates, and accommodation. Available only when the venue has function space. |
| 4     | A booking that only has accommodation. Available only when the venue has accommodation.                                        |

### Booking Status

The following booking status options are supported when adding a new booking.

| Value | Description      |
| ----- | ---------------- |
| 1     | Prospective      |
| 2     | Tentative        |
| 3     | Confirmed        |
| 5     | Ordering         |
| 9     | Prospective Hold |

### Accommodation Charging Methods

The following lists the accommodation charging method options.

| Value | Description         |
| ----- | ------------------- |
| 0     | None                |
| 1     | Individual Pays Own |
| 2     | Bill to Master      |
| 3     | Combined            |
| 4     | Complimentary       |

### Accommodation Reservation Methods

The following lists the accommodation reservation method options.

| Value | Description        |
| ----- | ------------------ |
| 1     | Rooming List       |
| 2     | Individual Call-In |
| 3     | Booking Engine     |
| 4     | Housing Form       |

### Accommodation Arrival Methods

The following lists the accommodation arrival method options.

| Value | Description  |
| ----- | ------------ |
| 1     | Together     |
| 2     | Individually |

### Custom Field

A booking custom field is an object with the following details.

| Property   | Type    | Required | Description                                                                       |
| ---------- | ------- | -------- | --------------------------------------------------------------------------------- |
| fieldId    | integer | required | The unique id of the booking custom field                                         |
| fieldValue | mixed   | required | The value of the booking custom field. Depends on the type of custom field value. |

### External URL Field

An External URL field is an object with the following details.

| Property | Type   | Required | Description                                                                                                                                                |
| -------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ref      | string | required | The unique reference key of the external URL                                                                                                               |
| url      | string | optional | The url link (https) scheme eg. <https://example.com> When the value is null, the external url record will be removed based on the provided reference key. |
| label    | string | optional | The label of the URL to display.                                                                                                                           |

### Special Considerations

#### Assigning a company/contact to the booking

The *contact type* of a booking is either a *company* **or** a *contact*. When *companyId* **or** *company* is present in the request then the *contact type* of the booking is set to *company*, and the *contactId* **or** *contact* must be a contact that belongs to that company. Otherwise the *contact type* of the booking is set to *contact* and contactId can be any valid contact in the venue's account.

If *contact* and *company* are present in request then it will link given contact to company.

A quote (i.e. booking status is *prospective*) that is assigned to an opportunity is forced to have the same *companyId* and *contactId* of the opportunity. Trying to change these values to something else will have no effect when updating the quote.

#### Adding an event template to a new booking

Setting *packageId* in the request when adding a *new* booking will attempt to add that event template to *all* event days of the booking *after* the booking is created. There is no guarantee that the event template will be successfully added to all days of the booking. When the event template cannot be added to the booking, one or more [warnings](#response-warnings) will be returned in the response.

There are also the following additional restrictions:

* An event template can only be added when the venue has function spaces.
* An event template can only be added to a [detailed](#booking-type) booking.
* The maximum number of event days when adding an event template is 7.
* *packagePrice* will be rounded to 3 decimal places if present in the request.

#### Booking coordinator

The coordinator (*bookedById*) is optional. A booking can be added or updated without a coordinator, so it can be created before the venue decides who will coordinate it.

* When *bookedById* is set, it must be the id of an active, billable user in the venue's account.
* When *bookedById* is not in the request, a new booking is added without a coordinator, and an existing booking keeps its current coordinator.
* When *bookedById* is null, the coordinator is removed from the booking.

When a booking has no coordinator:

* Booking tasks that would be assigned to the coordinator are created unassigned.
* Emails that would be sent to the coordinator are not sent.
* [getBooking](https://developer.ivvy.com/venues/getoraddbookingdata/get-booking.md) and [getBookingList](https://developer.ivvy.com/venues/getoraddbookingdata/get-booking-list.md) return *bookedById* as null, and getBooking returns *bookedByUser* as null.

A user of the iVvy application must select a coordinator before saving a booking that has none.

#### Discounts on bookings from an external source

By default, a *discountCode* is applied to the booking without checking the discount's conditions, and the booking does not count as a use of the discount. Integrations acting on behalf of customers (e.g. booking engines) should set *isFromExternalSource* to true when they add the booking. From then on, a discount applied to the booking is validated in the same way as on the iVvy marketplace and enquiry forms, and the booking counts as a use of its discount.

Every condition set on the discount campaign is checked. Conditions that are not set are ignored. The discount campaign's settings are returned by [getDiscountCampaignList](https://developer.ivvy.com/venues/venuedata/get-discount-campaign-list.md).

| Condition              | Campaign setting                                    | Rule                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Available              | startDateTime, endDateTime, venueIds, venueGroupIds | The campaign is enabled, the current date and time is within its start and end, and it applies to the booking's venue (directly, or through a venue group).                                                                                                                                                                                                                                                     |
| Event dates            | dateEventStart, dateEventEnd                        | The booking's event start and end dates both fall within the campaign's event dates.                                                                                                                                                                                                                                                                                                                            |
| Event templates only   | forBookingItem                                      | When the campaign applies only to event templates (packages), the booking must have at least one event template.                                                                                                                                                                                                                                                                                                |
| Minimum pax            | minBookingAttendees                                 | The booking's number of attendees meets or exceeds the minimum. A booking with no attendees yet does not meet a minimum. For a booking with event templates, this is the largest number of attendees across its event templates and the minimum guaranteed attendees of its sessions. For a campaign that applies only to event templates, it is the number of attendees of the booking's first event template. |
| Minimum room nights    | minRoomNights                                       | The total room nights of the booking's accommodation meet or exceed the minimum. A booking without accommodation has 0 room nights.                                                                                                                                                                                                                                                                             |
| Minimum booking value  | minBookingValue, minBookingValueCostcenterIds       | The booking value meets or exceeds the minimum. The booking value is the booking total excluding tax and before any discount, counting only the cost centers in *minBookingValueCostcenterIds*. Not checked for campaigns that apply only to event templates.                                                                                                                                                   |
| Maximum number of uses | maxUse                                              | The discount has been used fewer than *maxUse* times. 0 means unlimited. See [how discount uses are counted](#how-discount-uses-are-counted).                                                                                                                                                                                                                                                                   |

When a request applies a discount, the booking is validated with the details it will have once the request is saved. For example, a request that applies a discount and changes *dateEventStart* is validated against the new event start date.

**Validation failures**

When the discount fails one or more conditions, the whole request is rejected and nothing on the booking is saved. The response is a 400 error with one message per failed condition, in the format `discountCode: <CODE>: <description>`:

```javascript
{
  "errorCode": 400,
  "message": "The request contains invalid data",
  "specificCode": 24298,
  "additionalMessages": [
    "discountCode: EVENT_DATES: The booking event dates are outside the dates the discount applies to.",
    "discountCode: MIN_PAX: The booking pax is below the discount's minimum pax."
  ]
}
```

| Code                    | Description                                                                                                                                                           |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| INVALID\_CODE           | The discount code does not exist.                                                                                                                                     |
| MAX\_USES\_REACHED      | The discount has reached its maximum number of uses. Returned on its own.                                                                                             |
| NOT\_AVAILABLE          | The discount is not enabled, not active at the current date and time, or does not apply to the venue. Returned without the other conditions, which cannot be checked. |
| PACKAGE\_ONLY           | The discount applies only to event templates, and the booking has none.                                                                                               |
| EVENT\_DATES            | The booking's event dates are outside the discount's event dates.                                                                                                     |
| MIN\_PAX                | The booking's number of attendees is below the discount's minimum pax.                                                                                                |
| MIN\_ROOM\_NIGHTS       | The booking's room nights are below the discount's minimum room nights.                                                                                               |
| MIN\_BOOKING\_VALUE     | The booking value is below the discount's minimum booking value.                                                                                                      |
| BOOKING\_VALUE\_PENDING | The booking value was still being recalculated after a recent change, so the minimum booking value could not be checked. Retry the request shortly.                   |

**When the discount is validated**

The discount is validated only when it is applied: when the booking is added with a *discountCode*, or when an update sends a *discountCode* different from the booking's current discount. An update that leaves out *discountCode*, or sends the booking's current discount code, does not validate the discount again. The booking keeps its discount even if it no longer meets the discount's conditions (e.g. the event dates move outside the discount's event dates), or the discount campaign has since ended, been disabled or no longer applies to the venue.

**How discount uses are counted**

* A booking from an external source counts as one use of its discount. Updating that booking does not count as another use.
* The maximum number of uses includes bookings that used the discount through the iVvy marketplace and enquiry forms, and bookings from an external source.
* Discounts on bookings that are not from an external source (e.g. bookings created in iVvy, or through this api action without *isFromExternalSource*) do not count as a use.
* A booking in *ordering* status does not count as a use.
* When a booking's discount is removed or changed to another discount, the booking no longer counts as a use of the original discount.

**Recommended workflow**

The booking value, pax and room nights depend on items that are added with other api actions after the booking is created (e.g. sessions, event templates and accommodation). Apply the discount as the last step, once the booking is complete:

1. Create the booking with addOrUpdateBooking, with *isFromExternalSource* set to true and without a *discountCode*.
2. Add the sessions, event templates and accommodation with their own api actions.
3. Call addOrUpdateBooking with the booking *id* and the *discountCode*.

A discount sent when the booking is created is validated against the booking as it is at that point, which usually has no sessions, event templates or accommodation yet.

#### Updating a booking

Updating a booking (i.e. by setting *id* in the request) is an overlay action. This means the request can include only the details of the booking to be changed. This does not necessarily mean the operation will succeed. For example, the request might include the *dateEventEnd* value, and not the *dateEventStart* value. This scenario will fail if the value of *dateEventEnd* is earlier than the current *dateEventStart* value of the booking.

### Response Warnings

| Value                | Description                                                                                                                                         |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| packageErrors        | The way the venue has configured the event template prevents it from being added to one or more event days of the booking.                          |
| packageSessionErrors | One or more sessions of the event template could not be added to the booking. This is usually caused by conflicting reservations on function space. |

### Unsupported Features

The following features are currently not supported by this api action:

* Recurring bookings
* *Simple* booking types
* Discount settings
* Commission settings
* Multi language content
