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
      }
    ]
  }
}