Sign in
Packages

Create an item choice on a package

Adds a new PackageItemChoice to a Package. The new choice is appended to the package's existing item_choices list. Every option's item_type must match the choice's offering_type and must reference an offering on the package's site that the authenticated user has access to.

Server-side defaults: when min_options is omitted it falls back to 1 (or 0 if optional: true); when max_options is omitted it falls back to 1. With max_options: 1 the option_budget is ignored. Only one hotel_room_reservation choice is allowed per package — attempting to create a second returns 422.

Requires the SETTINGS_MANAGE permission on the package's site.

post/shop/packages/{packageId}/item-choices

Request body

namestring

A short, customer-facing label for the choice.

descriptionstring nullable

A longer explanation rendered alongside the options at booking time.

min_optionsinteger nullable

Minimum number of options the customer must pick. Defaults to 1 (or 0 when optional is true) when omitted.

max_optionsinteger nullable

Maximum number of options the customer may pick. Defaults to 1 when omitted. With max_options: 1 any option_budget is ignored.

option_budgetinteger nullable

An "included" budget for the chosen options in the smallest currency unit. Each option uses its standalone price; the overall package price is bumped up by any excess over this budget.

auto_select_timeslotboolean

When true, the booking engine auto-picks a timeslot for this choice instead of asking the customer. Only allowed when offering_type is appointment.

hide_timesboolean

Hide individual option start times from the customer-facing booking flow.

optionalboolean

Whether the customer can skip this choice entirely.

visibleboolean

Whether the choice is visible to the customer. Hidden choices are only allowed for product offering types.

offering_type'appointment' | 'area_booking' | 'hotel_room_reservation' | 'product' | 'session' | 'table_reservation'

The type of offerings this choice's options reference. Only one hotel_room_reservation choice is allowed per package.

Example request

{
  "name": "Massage",
  "description": "Choose your type of massage.",
  "min_options": 1,
  "max_options": 1,
  "option_budget": 6000,
  "allocation": {
    "revenue_centre": "treatments",
    "amount": 4000
  },
  "visible": true,
  "offering_type": "appointment",
  "options": [
    {
      "id": "5dcb47800000000000000026",
      "item_type": "appointment",
      "price_change": 2000
    }
  ]
}

Response

A single PackageItemChoice on a Package.

Example response

{
  "data": {
    "id": "5dcb47800000000000000025",
    "allow_overlaps": true,
    "auto_select_timeslot": true,
    "description": "Choose your type of massage.",
    "hide_times": true,
    "name": "Massage",
    "max_options": 2,
    "min_options": 1,
    "option_budget": 2000,
    "optional": true,
    "options": [
      {
        "id": "5dcb47800000000000000026",
        "item_type": "appointment",
        "offering": {
          "id": "5e932c0901d210625e3a8766",
          "categories": [
            {
              "id": "5e932c0901d210625e3a8766",
              "name": "Massage"
            }
          ],
          "currency": "gbp",
          "description": "Choose from classic, deep tissue and Swedish massage",
          "discounted_price_from": 4500,
          "duration": 30,
          "durations": [
            30
          ],
          "has_availability": true,
          "image": {
            "file_name": "super-cool-photo.jpg",
            "mime_type": "image/jpeg",
            "original_url": "https://example.com/media/super-cool-photo.jpg",
            "size": 84256,
            "url": "https://example.com/media/super-cool-photo-thumbnail@2x.jpg"
          },
          "max_guests": 2,
          "min_guests": 2,
          "name": "60 minute massage",
          "price_from": 5000,
          "price_to": 6500,
          "type": "appointment"
        },
        "price_change": 2000
      }
    ],
    "start_time_rules": [
      {
        "absolute_time_from": "12:00",
        "absolute_time_to": "12:30",
        "relative_mins_to": 30
      }
    ],
    "visible": true
  }
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.