githubEdit

Self-Service Mapping

Send a list of listings to get the supplier to map them themselves

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.

Update Mappings

put

Send the complete list of mappings for this connection.

The request upserts by resellerReference and removes any existing mappings not included in the payload.

Body
Responses
chevron-right
200

Returns the updated mapping rows.

application/json

From capability octo/mappings.

resellerReferencestringRequired

Reseller reference value.

Example: RES-BOOK-10045
resellerStatusstring · nullableOptional

Reseller status value.

Example: CONFIRMED
resellerProductstring · nullableOptional

Reseller product value.

Example: grand-canyon-day-tour
productIdstring · nullableOptional

Product identifier.

Example: e7cc8bb4-8d1c-4848-8824-5dbedb718681
optionIdstring · nullableRequired

Option identifier.

Example: 94cdd032-3d32-416d-b0a4-abf8b7495b8b
unitIdstring · nullableOptional

Unit identifier.

Example: unit_adult
optionRequiredbooleanOptional

Whether option required is enabled.

Example: true
unitRequiredbooleanOptional

Whether unit required is enabled.

Example: true
validityDaysinteger · nullableOptional

Validity days numeric value.

Example: 2
webhookUrlstring · uri · nullableOptional

Webhook url URL.

Example: https://www.city-sightseeing.com
put
/mappings
200

Returns the updated mapping rows.

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.

List Mappings

get

Gets the current state of all mappings for the connection.

Query parameters
optionIdstringRequired

Filter by one mapped option ID (DEFAULT supported).

Example: 94cdd032-3d32-416d-b0a4-abf8b7495b8b
resellerReferencestringOptional

Filter by one reseller reference.

Example: RES-BOOK-10045
resellerStatusstringOptional

Filter by reseller status.

Example: CONFIRMED
productIdstringOptional

Filter by one mapped product ID.

Example: e7cc8bb4-8d1c-4848-8824-5dbedb718681
productIds[]arrayOptional

Filter by multiple mapped product IDs.

Example: [{"id":"89fe0192-ddcd-430a-b285-e1396a4725d2","title":"Sample"}]
optionIds[]arrayOptional

Filter by multiple mapped option IDs (DEFAULT supported).

Example: [{"id":"89fe0192-ddcd-430a-b285-e1396a4725d2","title":"Sample"}]
Responses
chevron-right
200

Returns an array of mapping rows.

application/json

From capability octo/mappings.

resellerReferencestringRequired

Reseller reference value.

Example: RES-BOOK-10045
resellerStatusstring · nullableOptional

Reseller status value.

Example: CONFIRMED
resellerProductstring · nullableOptional

Reseller product value.

Example: grand-canyon-day-tour
productIdstring · nullableOptional

Product identifier.

Example: e7cc8bb4-8d1c-4848-8824-5dbedb718681
optionIdstring · nullableRequired

Option identifier.

Example: 94cdd032-3d32-416d-b0a4-abf8b7495b8b
unitIdstring · nullableOptional

Unit identifier.

Example: unit_adult
optionRequiredbooleanOptional

Whether option required is enabled.

Example: true
unitRequiredbooleanOptional

Whether unit required is enabled.

Example: true
validityDaysinteger · nullableOptional

Validity days numeric value.

Example: 2
webhookUrlstring · uri · nullableOptional

Webhook url URL.

Example: https://www.city-sightseeing.com
get
/mappings
200

Returns an array of mapping rows.

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

AvailabilityBatchRow

Booking

MappingUpsertRequest

PackageAvailability

Last updated