# Multi-Booking Cart

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

This capability lets you create multiple bookings from the same supplier in a single cart. In Ventrata, a cart is called an order, and this document uses that term.

All order paths below are public `/octo` routes.

## Reserve Booking in an Order

This capability extends booking write routes from [Bookings](/octo-core/bookings.md#endpoints) so you can pass `orderId` to attach a booking to an existing order (or omit `orderId` to auto-create one).

## Order Fields Returned on Booking and Gift Responses

When using `octo/cart`, the booking response (and gift response when using `octo/gifts`) includes additional order-level fields.

When using this capability, if you omit `orderId` from the initial request, Ventrata creates a new order automatically and returns `orderId` in the response. You can then reuse `orderId` in future booking requests to attach bookings to the same order.

You can also provide `orderId` on `POST /gifts` (when `octo/gifts` is enabled) to attach a gift voucher to an existing order.

{% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/orders" method="post" %}
[openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/orders/{orderId}" method="get" %}
[openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media)
{% endopenapi %}

Field definitions are included in the operation schemas above.

{% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/orders/{orderId}" method="patch" %}
[openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/orders/{orderId}/preview" method="patch" %}
[openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/orders/{orderId}/extend" method="post" %}
[openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/orders/{orderId}/confirm" method="post" %}
[openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media)
{% endopenapi %}

If you're using the cart capability and want to set a `resellerReference` you should do so as a [booking update](/octo-core/bookings.md#booking-update) as there are no reseller references on the order level.

Once you call this method, each of the bookings and gifts contained within the order will be confirmed too.

{% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/orders/{orderId}" method="delete" %}
[openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media)
{% endopenapi %}

This endpoint performs order-level cancellation. Equivalent behavior is available via `POST /orders/{orderId}/cancel`.

{% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/orders/{orderId}/cancel" method="post" %}
[openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/orders" method="get" %}
[openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media)
{% endopenapi %}

At least one of the filter groups above is required for `GET /orders`.

{% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/orders/{orderId}/notify" method="post" %}
[openapi.yaml](https://221588849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M7bgGIyO7QYNOfUMfxh%2Fuploads%2Fgit-blob-fa2d8cb1d7297d352c2639e6c4c6a990f2add6d7%2Fopenapi.yaml?alt=media)
{% endopenapi %}

`POST /orders/{orderId}/notify` returns `200 OK` with an empty response body.

Order invoice and voucher delivery URLs are returned directly on serialized order/booking objects.

## Schema Additions (JSON)

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

### `Booking`

```json
{
  "// ...rest of booking object": "...",
  "orderId": "ord_20260514_9f3c21",
  "orderReference": "ORDER-2026-0514-1001",
  "orderInvoicePdfUrl": "https://www.city-sightseeing.com",
  "primary": true
}
```

### `BookingWriteRequest`

```json
{
  "// ...rest of booking write request object": "...",
  "orderId": "ord_20260514_9f3c21"
}
```

### `Error`

```json
{
  "// ...rest of error object": "...",
  "orderId": "ord_20260514_9f3c21"
}
```

### `Gift`

```json
{
  "// ...rest of gift object": "...",
  "orderId": "ord_20260514_9f3c21",
  "orderReference": "ORDER-2026-0514-1001",
  "orderInvoicePdfUrl": "https://www.city-sightseeing.com",
  "primary": true
}
```

### `GiftCreateRequest`

```json
{
  "// ...rest of gift create request object": "...",
  "orderId": "ord_20260514_9f3c21"
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ventrata.com/capabilities/cart.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.