# Self-Service Mapping

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

This capability allows you to send a "mapping sheet" of products that you need to map. This is then given to the supplier in a user-friendly form they can select which product each item maps to in their Ventrata system. Once the mapping has been set a webhook URL is called to notify your system of the change.

The mappings endpoints are available under `/octo`.

{% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/mappings" method="put" %}
[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 %}

Body must be a JSON array of mapping rows.

See the `PUT /mappings` operation above for request schema examples.

`resellerReference` is required on each item. Items are upserted by `resellerReference`, and any existing mappings not included in the array are removed.

Whenever a product in your system for this supplier has been changed, updated or deleted, you should repeat this request with all mappings. `PUT` synchronizes the full set for the connection.

After you make the request and new mappings are added, Ventrata sends a notification to the supplier to complete them.

Once the supplier chooses a product and option for a mapping, Ventrata sends a `POST` request to the URL provided in `webhookUrl` for that mapping row. The webhook body follows the mapping object schema and includes resolved `productId`, `optionId`, and `unitId` values.

The `unitId` and `optionId` will be null in the webhook request body if we set `unitRequired` and `optionRequired` to false respectively on the original mappings request.

Your response to this request must be `2XX` (for example `200 OK`), otherwise we retry until we receive a `2XX` response.

{% openapi src="/files/9aBZzqykFPaTU7bfbNrr" path="/mappings" 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 %}

#### Query Parameters

If both `productId` and `productIds[]` are provided, `productId` is used. If both `optionId` and `optionIds[]` are provided, `optionId` is used. Use repeated query keys for arrays, for example `productIds[]=id1&productIds[]=id2`. `DEFAULT` on `optionId`/`optionIds[]` filters for mappings without a stored option.

`optionId` and `unitId` may be `null` when no mapping has been selected yet, or when `optionRequired` / `unitRequired` is `false`.

## Booking and Availability Responses

When this capability is enabled, booking and availability responses include a `mappings` field. The array contains mappings for the response product/option combination.

* Booking responses include `booking.mappings`.
* Availability responses include `availability[].mappings`.

Each `mappings[]` item uses the same schema as the mappings list response.

## Schema Additions (JSON)

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

### `Availability`

```json
{
  "// ...rest of availability object": "...",
  "mappings": [
    {
      "resellerReference": "RES-BOOK-10045",
      "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b",
      "productId": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
      "resellerStatus": "CONFIRMED"
    }
  ]
}
```

### `AvailabilityBatchRow`

```json
{
  "// ...rest of availability batch row object": "...",
  "mappings": [
    {
      "resellerReference": "RES-BOOK-10045",
      "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b",
      "productId": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
      "resellerStatus": "CONFIRMED"
    }
  ]
}
```

### `Booking`

```json
{
  "// ...rest of booking object": "...",
  "mappings": [
    {
      "resellerReference": "RES-BOOK-10045",
      "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b",
      "resellerStatus": "CONFIRMED",
      "resellerProduct": "grand-canyon-day-tour",
      "productId": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
      "unitId": "unit_adult",
      "optionRequired": true,
      "unitRequired": true,
      "validityDays": 2,
      "webhookUrl": "https://www.city-sightseeing.com"
    }
  ]
}
```

### `MappingUpsertRequest`

```json
{
  "// ...rest of mapping upsert request object": "...",
  "mappings": [
    {
      "resellerReference": "RES-BOOK-10045",
      "productId": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
      "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b"
    }
  ]
}
```

### `PackageAvailability`

```json
{
  "// ...rest of package availability object": "...",
  "mappings": [
    {
      "resellerReference": "RES-BOOK-10045",
      "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b",
      "productId": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
      "resellerStatus": "CONFIRMED"
    }
  ]
}
```


---

# 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/mappings.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.