Promotions / Offers

Adds the ability to apply offer codes, automatic public offers, comparisons, and combination discounts

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

This capability depends on octo/pricing.

Related capabilities:

octo/cart is required for offerCombinations on order responses.
octo/gifts is required for gift offer endpoints/fields.
octo/extras is required for offer fields on extraItems.

All routes below are under the /octo prefix.

The offers capability lets you apply promotion codes to bookings/gifts, automatically apply eligible public offers, return upsell comparisons, and return discounted product combinations.

Combination Product Discovery

This capability extends product routes documented in Products:

GET /products
GET /products/{productId}

When offerCode is a combination code (combination_<...>), product scope is expanded to include the combination target product, so you can fetch product/options/availability for that target using the same code.

Offer Object

The same offer object is used in:

offers[] and offer on availability responses
offer and offers[] on booking/gift/extra-item responses
offer in offerCombinations[]

List Supplier Offers

get

List supplier promotions serialized as offer objects.

Responses

200

Successful response

application/json

From capability octo/offers.

idstring · uuidRequired

Unique identifier for this resource.

Example: 89fe0192-ddcd-430a-b285-e1396a4725d2

tagsstring[]Optional

List of tag values.

Example: ["vip","partner"]

titlestringOptional

Public title of the offer.

Example: Summer Promotion

labelstringOptional

Discount label shown to customers.

Example: Save 20%

codestringOptional

Offer code identifier.

Example: SUMMER25

descriptionstring · nullableOptional

Offer description shown to the customer.

Example: 20% off selected departures this month.

netDiscountstring · enum · nullableOptional

How the discount is applied to net pricing.

Example: FULLPossible values:

usablebooleanOptional

Whether the offer is currently usable in the given context.

Example: true

unusableReasonstring · nullableOptional

Reason the offer cannot be applied in the current context.

Example: Offer is not valid for the selected date.

get

/offers

GET /octo/offers HTTP/1.1
Host: api.ventrata.com
Accept: */*

200

Successful response

[
  {
    "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
    "tags": [
      "vip",
      "partner"
    ],
    "title": "Summer Promotion",
    "label": "Save 20%",
    "code": "SUMMER25",
    "description": "20% off selected departures this month.",
    "netDiscount": "FULL",
    "restrictions": {
      "minUnits": 1,
      "maxUnits": 10,
      "minTotal": 0,
      "maxTotal": 50000,
      "unitIds": [
        "3d6f0a3a-59d4-4b16-a0c5-11d2d8a4e6b7",
        "6b65fd83-4a1f-4744-8f4a-c24d8d770f29"
      ]
    },
    "usable": true,
    "unusableReason": "Offer is not valid for the selected date.",
    "membershipBenefit": {
      "id": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
      "title": "Summer Promotion",
      "description": "Morning departure with central pickup included."
    }
  }
]

Pricing Field Added By Offers

Offers adds offerDiscount to pricing fragments emitted through pricing serializers, including:

availability pricing / pricingFrom
availability unitPricing[] / unitPricingFrom[]
booking/gift/order pricing
unit item / purchase item / extra item pricing

Get Available Offers

This capability extends availability routes documented in Availability:

POST /availability
POST /availability/calendar
POST /availability/batch
POST /availability/calendar/batch

Response Additions Per Availability Object

If no offerCode is sent, new booking/gift flows auto-select the first eligible public offer.

Discount Booking

Offer code can be sent on these booking write routes:

POST /bookings
PATCH /bookings/{uuid}
POST /bookings/{uuid}/confirm

Base booking schema: Bookings.

It can also be sent inside order payloads on:

bookings[].offerCode in POST /orders, PATCH /orders/:orderId, PATCH /orders/:orderId/preview, POST /orders/:orderId/confirm

Booking Response Additions

These fields are present on any serialized booking response, including:

GET /bookings/{uuid}
GET /bookings
booking write responses
bookings embedded in serialized order responses

Product Comparisons

Comparisons are exposed on serialized booking objects from base booking routes (see Bookings).

offerComparisons[] is returned on booking objects (including booking responses embedded in order responses).

Comparisons are returned only for persisted, active, standalone, non-combination bookings; otherwise the field is [].

Product Combinations

Combinations are exposed on serialized order objects from base cart routes (see Multi-Booking Cart).

Combinations are returned on order objects as offerCombinations[] (requires octo/cart). They are also present on other order responses that serialize an order (POST/PATCH /orders, GET /orders, etc.).

To apply a combination, create/update a booking with the returned offerCode and matching productId/optionId.

Gift Offers

Requires octo/gifts.

Offer code can be sent on:

POST /gifts
PATCH /gifts/{uuid}
PATCH /gifts/{uuid}/preview
POST /gifts/{uuid}/confirm
gifts[].offerCode in order create/update payloads

These fields are present on:

GET /gifts/{uuid}
GET /gifts
gift write responses
gifts embedded in serialized order responses
offerCode
offerTitle
offerComparisons (always [])
offerIsCombination (always false)
offer
offers[]
pricing.offerDiscount

Base gift schema: Gift Vouchers.

Extra Item Offers

Requires octo/extras.

Each serialized extra item (booking.extraItems[] and booking.unitItems[].extraItems[]) includes:

offerCode
offerTitle
offerComparisons (always [])
offerIsCombination (always false)
offer
offers[]
pricing.offerDiscount

List Supplier Offers

get

List supplier promotions serialized as offer objects.

Responses

200

Successful response

application/json

From capability octo/offers.

idstring · uuidRequired

Unique identifier for this resource.

Example: 89fe0192-ddcd-430a-b285-e1396a4725d2

tagsstring[]Optional

List of tag values.

Example: ["vip","partner"]

titlestringOptional

Public title of the offer.

Example: Summer Promotion

labelstringOptional

Discount label shown to customers.

Example: Save 20%

codestringOptional

Offer code identifier.

Example: SUMMER25

descriptionstring · nullableOptional

Offer description shown to the customer.

Example: 20% off selected departures this month.

netDiscountstring · enum · nullableOptional

How the discount is applied to net pricing.

Example: FULLPossible values:

usablebooleanOptional

Whether the offer is currently usable in the given context.

Example: true

unusableReasonstring · nullableOptional

Reason the offer cannot be applied in the current context.

Example: Offer is not valid for the selected date.

get

/offers

GET /octo/offers HTTP/1.1
Host: api.ventrata.com
Accept: */*

200

Successful response

[
  {
    "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
    "tags": [
      "vip",
      "partner"
    ],
    "title": "Summer Promotion",
    "label": "Save 20%",
    "code": "SUMMER25",
    "description": "20% off selected departures this month.",
    "netDiscount": "FULL",
    "restrictions": {
      "minUnits": 1,
      "maxUnits": 10,
      "minTotal": 0,
      "maxTotal": 50000,
      "unitIds": [
        "3d6f0a3a-59d4-4b16-a0c5-11d2d8a4e6b7",
        "6b65fd83-4a1f-4744-8f4a-c24d8d770f29"
      ]
    },
    "usable": true,
    "unusableReason": "Offer is not valid for the selected date.",
    "membershipBenefit": {
      "id": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
      "title": "Summer Promotion",
      "description": "Morning departure with central pickup included."
    }
  }
]

Returns paginated supplier promotions serialized as the offer object above.

GET /offers returns supplier promotions sorted by position. Usability in this endpoint is not availability-specific; contextual usability is returned on availability/booking/gift/extra responses.

Schema Additions (JSON)

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

`Availability`

{
  "// ...rest of availability object": "...",
  "offerCode": "SUMMER25",
  "offerTitle": "Summer Promotion",
  "offerIsCombination": true,
  "offerComparisons": [
    {
      "offerCode": "SUMMER25",
      "offerTitle": "Summer Promotion",
      "pricing": {
        "original": 2300,
        "retail": 2300,
        "net": 1610,
        "currency": "EUR",
        "currencyPrecision": 2,
        "includedTaxes": [
          {
            "name": "10%",
            "shortDescription": null,
            "original": 209,
            "retail": 209,
            "net": 146
          }
        ]
      },
      "offer": {
        "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
        "title": "Summer Promotion",
        "code": "SUMMER25"
      }
    }
  ],
  "offer": {
    "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
    "title": "Summer Promotion",
    "code": "SUMMER25"
  },
  "offers": [
    {
      "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
      "title": "Summer Promotion",
      "code": "SUMMER25"
    }
  ]
}

`AvailabilityBatchRequest`

{
  "// ...rest of availability batch request object": "...",
  "offerCode": "SUMMER25"
}

`AvailabilityBatchRow`

{
  "// ...rest of availability batch row object": "...",
  "offerCode": "SUMMER25",
  "offerTitle": "Summer Promotion",
  "offerIsCombination": true,
  "offerComparisons": [
    {
      "offerCode": "SUMMER25",
      "offerTitle": "Summer Promotion",
      "pricing": {
        "original": 2300,
        "retail": 2300,
        "net": 1610,
        "currency": "EUR",
        "currencyPrecision": 2,
        "includedTaxes": [
          {
            "name": "10%",
            "shortDescription": null,
            "original": 209,
            "retail": 209,
            "net": 146
          }
        ]
      },
      "offer": {
        "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
        "title": "Summer Promotion",
        "code": "SUMMER25"
      }
    }
  ],
  "offer": {
    "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
    "title": "Summer Promotion",
    "code": "SUMMER25"
  },
  "offers": [
    {
      "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
      "title": "Summer Promotion",
      "code": "SUMMER25"
    }
  ]
}

`AvailabilityCalendar`

{
  "// ...rest of availability calendar object": "...",
  "offer": {
    "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
    "title": "Summer Promotion",
    "code": "SUMMER25"
  },
  "offers": [
    {
      "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
      "title": "Summer Promotion",
      "code": "SUMMER25"
    }
  ],
  "offerCode": "SUMMER25",
  "offerTitle": "Summer Promotion",
  "offerIsCombination": true,
  "offerComparisons": [
    {
      "offerCode": "SUMMER25",
      "offerTitle": "Summer Promotion",
      "pricing": {
        "original": 2300,
        "retail": 2300,
        "net": 1610,
        "currency": "EUR",
        "currencyPrecision": 2,
        "includedTaxes": [
          {
            "name": "10%",
            "shortDescription": null,
            "original": 209,
            "retail": 209,
            "net": 146
          }
        ]
      },
      "offer": {
        "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
        "title": "Summer Promotion",
        "code": "SUMMER25"
      }
    }
  ]
}

`AvailabilityCalendarBatchRequest`

{
  "// ...rest of availability calendar batch request object": "...",
  "offerCode": "SUMMER25"
}

`AvailabilityCalendarBatchRow`

{
  "// ...rest of availability calendar batch row object": "...",
  "offer": {
    "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
    "title": "Summer Promotion",
    "code": "SUMMER25"
  },
  "offers": [
    {
      "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
      "title": "Summer Promotion",
      "code": "SUMMER25"
    }
  ],
  "offerCode": "SUMMER25",
  "offerTitle": "Summer Promotion",
  "offerIsCombination": true,
  "offerComparisons": [
    {
      "offerCode": "SUMMER25",
      "offerTitle": "Summer Promotion",
      "pricing": {
        "original": 2300,
        "retail": 2300,
        "net": 1610,
        "currency": "EUR",
        "currencyPrecision": 2,
        "includedTaxes": [
          {
            "name": "10%",
            "shortDescription": null,
            "original": 209,
            "retail": 209,
            "net": 146
          }
        ]
      },
      "offer": {
        "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
        "title": "Summer Promotion",
        "code": "SUMMER25"
      }
    }
  ]
}

`AvailabilityCalendarRequest`

{
  "// ...rest of availability calendar request object": "...",
  "offerCode": "SUMMER25"
}

`AvailabilityRequest`

{
  "// ...rest of availability request object": "...",
  "offerCode": "SUMMER25"
}

`Booking`

{
  "// ...rest of booking object": "...",
  "offerCode": "SUMMER25",
  "offerTitle": "Summer Promotion",
  "offerIsCombination": true,
  "offerComparisons": [
    {
      "offerCode": "SUMMER25",
      "offerTitle": "Summer Promotion",
      "pricing": {
        "original": 22000,
        "retail": 20000,
        "net": 18000,
        "currency": "USD",
        "currencyPrecision": 2,
        "includedTaxes": [
          {
            "name": "Sales Tax",
            "shortDescription": "Local sales tax",
            "original": 2000,
            "retail": 1800,
            "net": 1600
          }
        ],
        "offerDiscount": {
          "retail": 2000,
          "net": 2000,
          "includedTaxes": [
            {
              "name": "Sales Tax",
              "shortDescription": "Local sales tax",
              "retail": 200,
              "net": 200
            }
          ]
        }
      },
      "offer": {
        "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
        "title": "Summer Promotion",
        "code": "SUMMER25"
      }
    }
  ],
  "offer": {
    "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
    "internalName": "Morning City Tour",
    "title": "Summer Promotion",
    "shortDescription": "Central departure with multilingual guide.",
    "code": "SUMMER25",
    "publicOfferId": "public_offer_id-example",
    "usable": true,
    "unusableReason": "Offer is not valid for the selected date.",
    "offerDiscount": {
      "retail": 2000,
      "net": 2000,
      "includedTaxes": [
        {
          "name": "Sales Tax",
          "shortDescription": "Local sales tax",
          "retail": 200,
          "net": 200
        }
      ]
    },
    "membershipBenefit": {
      "id": "94cdd032-3d32-416d-b0a4-abf8b7495b8b",
      "title": "VIP Member Discount",
      "description": "Reduced pricing for active members."
    },
    "tags": [
      "vip",
      "partner"
    ],
    "status": "CONFIRMED"
  },
  "offers": [
    {
      "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
      "internalName": "Morning City Tour",
      "title": "Summer Promotion",
      "shortDescription": "Central departure with multilingual guide.",
      "code": "SUMMER25",
      "publicOfferId": "public_offer_id-example",
      "usable": true,
      "unusableReason": "Offer is not valid for the selected date.",
      "offerDiscount": {
        "retail": 2000,
        "net": 2000,
        "includedTaxes": [
          {
            "name": "Sales Tax",
            "shortDescription": "Local sales tax",
            "retail": 200,
            "net": 200
          }
        ]
      },
      "membershipBenefit": {
        "id": "94cdd032-3d32-416d-b0a4-abf8b7495b8b",
        "title": "VIP Member Discount",
        "description": "Reduced pricing for active members."
      },
      "tags": [
        "vip",
        "partner"
      ],
      "status": "CONFIRMED"
    }
  ]
}

`BookingUnitItem`

{
  "// ...rest of booking unit item object": "...",
  "offerCode": "SUMMER25",
  "offerTitle": "Summer Promotion",
  "offerIsCombination": true,
  "offerComparisons": [
    {
      "offerCode": "SUMMER25",
      "offerTitle": "Summer Promotion",
      "pricing": {
        "original": 2300,
        "retail": 2300,
        "net": 1610,
        "currency": "EUR",
        "currencyPrecision": 2,
        "includedTaxes": [
          {
            "name": "10%",
            "shortDescription": null,
            "original": 209,
            "retail": 209,
            "net": 146
          }
        ]
      },
      "offer": {
        "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
        "title": "Summer Promotion",
        "code": "SUMMER25"
      }
    }
  ],
  "offer": {
    "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
    "title": "Summer Promotion",
    "code": "SUMMER25"
  },
  "offers": [
    {
      "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
      "title": "Summer Promotion",
      "code": "SUMMER25"
    }
  ]
}

`BookingWriteRequest`

{
  "// ...rest of booking write request object": "...",
  "offerCode": "SUMMER25"
}

`ExtraPricing`

{
  "// ...rest of extra pricing object": "...",
  "offerDiscount": {
    "retail": 2000,
    "net": 2000,
    "includedTaxes": [
      {
        "name": "Sales Tax",
        "shortDescription": "Local sales tax",
        "retail": 200,
        "net": 200
      }
    ]
  }
}

`Gift`

{
  "// ...rest of gift object": "...",
  "offerCode": "SUMMER25",
  "offerTitle": "Summer Promotion",
  "offerIsCombination": true,
  "offerComparisons": [
    {
      "offerCode": "SUMMER25",
      "offerTitle": "Summer Promotion",
      "pricing": {
        "original": 2300,
        "retail": 2300,
        "net": 1610,
        "currency": "EUR",
        "currencyPrecision": 2,
        "includedTaxes": [
          {
            "name": "10%",
            "shortDescription": null,
            "original": 209,
            "retail": 209,
            "net": 146
          }
        ]
      },
      "offer": {
        "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
        "title": "Summer Promotion",
        "code": "SUMMER25"
      }
    }
  ],
  "offer": {
    "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
    "title": "Summer Promotion",
    "code": "SUMMER25"
  },
  "offers": [
    {
      "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
      "title": "Summer Promotion",
      "code": "SUMMER25"
    }
  ]
}

`GiftCreateRequest`

{
  "// ...rest of gift create request object": "...",
  "offerCode": "SUMMER25"
}

`Money`

{
  "// ...rest of money object": "...",
  "offerDiscount": {
    "retail": 2000,
    "net": 2000,
    "includedTaxes": [
      {
        "name": "Sales Tax",
        "shortDescription": "Local sales tax",
        "retail": 200,
        "net": 200
      }
    ]
  }
}

`Offer`

{
  "// ...rest of offer object": "...",
  "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
  "tags": [
    "vip",
    "partner"
  ],
  "title": "Summer Promotion",
  "label": "Save 20%",
  "code": "SUMMER25",
  "description": "20% off selected departures this month.",
  "netDiscount": "FULL",
  "restrictions": {
    "minUnits": 1,
    "maxUnits": 10,
    "minTotal": 0,
    "maxTotal": 50000,
    "unitIds": [
      "3d6f0a3a-59d4-4b16-a0c5-11d2d8a4e6b7",
      "6b65fd83-4a1f-4744-8f4a-c24d8d770f29"
    ]
  },
  "usable": true,
  "unusableReason": null
}

`Order`

{
  "// ...rest of order object": "...",
  "offerCombinations": [
    {
      "productId": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
      "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b",
      "units": [
        {
          "unitId": "3d6f0a3a-59d4-4b16-a0c5-11d2d8a4e6b7",
          "quantity": 2
        }
      ],
      "offerCode": "SUMMER25"
    }
  ]
}

`OrderUpdateRequest`

{
  "// ...rest of order update request object": "...",
  "offers": [
    "offer-example"
  ]
}

`PackageAvailability`

{
  "// ...rest of package availability object": "...",
  "offerCode": "SUMMER25",
  "offerTitle": "Summer Promotion",
  "offerIsCombination": true,
  "offerComparisons": [
    {
      "offerCode": "SUMMER25",
      "offerTitle": "Summer Promotion",
      "pricing": {
        "original": 2300,
        "retail": 2300,
        "net": 1610,
        "currency": "EUR",
        "currencyPrecision": 2,
        "includedTaxes": [
          {
            "name": "10%",
            "shortDescription": null,
            "original": 209,
            "retail": 209,
            "net": 146
          }
        ]
      },
      "offer": {
        "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
        "title": "Summer Promotion",
        "code": "SUMMER25"
      }
    }
  ],
  "offer": {
    "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
    "title": "Summer Promotion",
    "code": "SUMMER25"
  },
  "offers": [
    {
      "id": "89fe0192-ddcd-430a-b285-e1396a4725d2",
      "title": "Summer Promotion",
      "code": "SUMMER25"
    }
  ]
}

`Pricing`

{
  "// ...rest of pricing object": "...",
  "offerDiscount": {
    "retail": 2000,
    "net": 2000,
    "includedTaxes": [
      {
        "name": "Sales Tax",
        "shortDescription": "Local sales tax",
        "retail": 200,
        "net": 200
      }
    ]
  }
}

`UnitPricing`

{
  "// ...rest of unit pricing object": "...",
  "offerDiscount": {
    "retail": 2000,
    "net": 2000,
    "includedTaxes": [
      {
        "name": "Sales Tax",
        "shortDescription": "Local sales tax",
        "retail": 200,
        "net": 200
      }
    ]
  }
}

PreviousContent NextExtras

Last updated 9 days ago

hashtagCombination Product Discovery

hashtagOffer Object

hashtagList Supplier Offers

hashtagPricing Field Added By Offers

hashtagGet Available Offers

hashtagResponse Additions Per Availability Object

hashtagDiscount Booking

hashtagBooking Response Additions

hashtagProduct Comparisons

hashtagProduct Combinations

hashtagGift Offers

hashtagExtra Item Offers

hashtagList Supplier Offers

hashtagSchema Additions (JSON)

hashtagAvailability

hashtagAvailabilityBatchRequest

hashtagAvailabilityBatchRow

hashtagAvailabilityCalendar

hashtagAvailabilityCalendarBatchRequest

hashtagAvailabilityCalendarBatchRow

hashtagAvailabilityCalendarRequest

hashtagAvailabilityRequest

hashtagBooking

hashtagBookingUnitItem

hashtagBookingWriteRequest

hashtagExtraPricing

hashtagGift

hashtagGiftCreateRequest

hashtagMoney

hashtagOffer

hashtagOrder

hashtagOrderUpdateRequest

hashtagPackageAvailability

hashtagPricing

hashtagUnitPricing

Combination Product Discovery

Offer Object

List Supplier Offers

Pricing Field Added By Offers

Get Available Offers

Response Additions Per Availability Object

Discount Booking

Booking Response Additions

Product Comparisons

Product Combinations

Gift Offers

Extra Item Offers

List Supplier Offers

Schema Additions (JSON)

`Availability`

`AvailabilityBatchRequest`

`AvailabilityBatchRow`

`AvailabilityCalendar`

`AvailabilityCalendarBatchRequest`

`AvailabilityCalendarBatchRow`

`AvailabilityCalendarRequest`

`AvailabilityRequest`

`Booking`

`BookingUnitItem`

`BookingWriteRequest`

`ExtraPricing`

`Gift`

`GiftCreateRequest`

`Money`

`Offer`

`Order`

`OrderUpdateRequest`

`PackageAvailability`

`Pricing`

`UnitPricing`