Offerings catalog

Packages

A Package represents a collection of Offerings that can be purchased together.

get/shop/packages

List packages

listPackages

Returns a paginated list of Packages configured at the given site, ordered by name. Use this to power a settings dashboard or to populate a shopfront browse page. The list includes archived (soft-deleted) packages only when archived=true is passed.

Requires the RESERVATIONS_VIEW permission on the site. Pass include_option_offerings=true to embed each item choice's option offering details (helpful when rendering the package contents inline).

Query parameters

  • site_idstringrequired

    Filter results by the site they belong to

  • pageintegeroptional

    The page to retrieve results from

  • per_pageintegeroptional

    The number of results to return per page

  • archivedbooleanoptional

    Whether to include archived resources in the response. When true, archived resources are returned; when false or omitted, only non-archived resources are returned.

  • category_idstringoptional

    Filter results to packages that include the given category in their category_ids. Comma-separate to OR multiple categories (e.g. category_id=5e932c0901d210625e3a8766,5e932c0901d210625e3a8767).

  • include_option_offeringsbooleanoptional

    When true, each Package's item_choices[].options[].offering is populated with a hydrated PackageShopOffering (name, price, image, etc.) — useful when rendering the package contents on an admin page without making a follow-up request per option. Defaults to false to keep responses small.

Responses

  • 200

    A paginated list of Packages for the requested site.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

post/shop/packages

Create a package

createPackage

Creates a new Package at the given site. The minimum body is name + site_id; everything else has sensible defaults. Requires the SETTINGS_MANAGE permission on site_id.

Server-side behaviour worth noting:

  • separate_couples_package_choices is forced to false unless both min_guests and max_guests equal 2.
  • permitted_membership_type_ids is filtered to membership types within the site's brand; others are silently dropped.
  • When overnight_package_config.enabled=true, both rate_id and num_nights are required — otherwise the request fails with 422.
  • organisation_id defaults to the caller's primary organisation when omitted.

Query parameters

  • site_idstringrequired

    Filter results by the site they belong to

  • pageintegeroptional

    The page to retrieve results from

  • per_pageintegeroptional

    The number of results to return per page

  • archivedbooleanoptional

    Whether to include archived resources in the response. When true, archived resources are returned; when false or omitted, only non-archived resources are returned.

  • category_idstringoptional

    Filter results to packages that include the given category in their category_ids. Comma-separate to OR multiple categories (e.g. category_id=5e932c0901d210625e3a8766,5e932c0901d210625e3a8767).

  • include_option_offeringsbooleanoptional

    When true, each Package's item_choices[].options[].offering is populated with a hydrated PackageShopOffering (name, price, image, etc.) — useful when rendering the package contents on an admin page without making a follow-up request per option. Defaults to false to keep responses small.

Request body

  • namestringrequired

    Display name for the package. Visible to customers in the shopfront and to staff in the admin UI. Plain text only.

  • descriptionstringoptional

    Long-form description shown to customers when they're browsing the package. Markdown is rendered.

  • product_codestringoptionalnullable

    Optional product code used to map this package to an external POS or PMS catalog. Free-form string; uniqueness is not enforced server-side.

  • external_idstringoptionalnullable

    External identifier used by integrations to reference this offering. Free-form.

  • currencystringoptional

    The ISO-4217 currency code.

  • site_idstringrequired

    ID of the site to offer this package at. The caller's API key must have access to the site; requests for a site they don't own get 422.

  • organisation_iduuidoptional

    Optional organisation to attribute this offering to. Defaults to the caller's primary organisation if omitted.

  • availability_rulesobject[]optional

    Per-day availability rules controlling when this package can be booked. See AvailabilityRule for shape.

  • offered_onlinebooleanoptional

    When true, the package is bookable via the public shopfront. When false, it's bookable only via the admin UI. Defaults to false.

  • privatebooleanoptional

    When true, only customers with the direct link can book this package — it's hidden from category pages and search engines.

  • visibilitystringoptional

    Visibility override controlling who can see this package on the shopfront. public shows it everywhere; link_only keeps it out of browse/search (still bookable by direct link); private restricts it to admin booking flows.

    Possible values:publiclink_onlyprivate
  • customers_onlybooleanoptional

    When true, only registered customers (not guests) can book this package.

  • members_onlybooleanoptional

    When true, only members of permitted membership types can book this package.

  • permitted_membership_type_idsstring[]optionalnullable

    Membership type IDs whose members are allowed to book this package. Only relevant when members_only=true. Membership types from outside the site's brand are silently filtered out.

  • membership_booking_windows_enabledbooleanoptional

    When true, members can book this package further in advance than the standard window. The exact extra advance per membership type is defined in membership_booking_windows.

  • membership_booking_windowsobject[]optional

    Per-membership-type advance-booking-window overrides.

  • item_choicesobject[]optional

    The choices customers make when booking this package (e.g. "pick a massage", "pick a lunch course"). Each choice has an allocation, options, start-time rules, and visibility flags. The detailed shape is documented as PackageItemChoice under the Package schema — the create endpoint accepts the same object shape.

  • upsell_offeringsobject[]optional

    Other offerings to upsell on the booking confirmation page.

  • cross_sell_offeringsobject[]optional

    Other offerings to cross-sell during the booking flow.

  • category_idsstring[]optional

    Category IDs the package belongs to. Used for shopfront grouping.

  • metaobjectoptional

    SEO metadata for the public shopfront page.

  • customer_cancellation_permittedstringoptionalnullable

    Whether and when customers can cancel a booking of this package themselves. allowed = always; if_unpaid = only if no payment has been taken; disallowed = never (admin only).

    Possible values:allowedif_unpaiddisallowed
  • customer_cancellation_min_durationstringoptionalnullable

    ISO 8601 duration before the package's start during which cancellation is no longer permitted. e.g. PT24H = no cancellation in the last 24 hours.

  • max_daily_durationintegeroptionalnullable

    Maximum minutes between the start of the first and end of the last item on each day of the package. Use this to cap how spread-out a single-day package can become.

  • max_advance_bookings_intervalstringoptionalnullable

    ISO 8601 duration limiting how far in advance customers can book this package. e.g. P2W = up to two weeks ahead.

  • min_advance_bookings_intervalstringoptionalnullable

    ISO 8601 duration limiting how soon before the package start a customer can book. e.g. P2D = at least two days' notice.

  • min_guestsintegeroptionalnullable

    Minimum number of guests for a single booking of this package.

  • max_guestsintegeroptionalnullable

    Maximum number of guests for a single booking. Must be >= min_guests. Server-side, separate_couples_package_choices is forced to false unless both min_guests and max_guests equal 2.

  • prevent_choice_overlapsbooleanoptionalnullable

    Whether to prevent booking choices in this package from overlapping times.

  • separate_couples_package_choicesbooleanoptionalnullable

    For couples packages (both min_guests and max_guests equal 2), whether each guest can independently pick choices. Forced to false for any other guest configuration.

  • email_optionsobjectoptional

    Email-rendering options for this package.

  • overnight_package_configobjectoptional

    Configuration for overnight packages — packages that include a hotel room reservation alongside their other items. When enabled=true, both rate_id and num_nights are required.

  • include_pricing_on_calendarbooleanoptional

    Whether to surface the price alongside this package in calendar views.

  • max_per_basketintegeroptionalnullable

    Maximum bookings of this package per basket.

  • max_per_guestintegeroptionalnullable

    Maximum bookings of this package per individual guest within a basket.

Responses

  • 201

    A single Package.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 422

    The request didn't pass validation

get/shop/packages/{packageId}

Retrieve a Package

getPackage

Use this endpoint to retrieve a single Package model.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

Query parameters

  • basketItemIdobject-idoptional

    The ID of the basket item associated with the package. If provided, the returned package will include additional fields relevant to the basket item.

Responses

  • 200

    The Package was successfully retrieved.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

put/shop/packages/{packageId}

Update a package

updatePackage

Partially updates a Package. Every field is optional; only fields you send are written. Fields you omit retain their current values.

Requires the SETTINGS_MANAGE permission on the package's site. site_id and organisation_id are fixed at create time and cannot be changed here. Server-side, the same separate_couples_package_choices and permitted_membership_type_ids rules apply as on create.

When overnight_package_config.enabled flips, the package's hotel-room item choice is created (or removed) automatically — you don't need to send it explicitly.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

Query parameters

  • basketItemIdobject-idoptional

    The ID of the basket item associated with the package. If provided, the returned package will include additional fields relevant to the basket item.

Request body

  • namestringoptional

    Display name. Plain text only.

  • descriptionstringoptional

    Long-form description shown to customers. Markdown is rendered.

  • product_codestringoptionalnullable

    External POS/PMS product code.

  • external_idstringoptionalnullable

    External identifier used by integrations.

  • currencystringoptional

    The ISO-4217 currency code.

  • availability_rulesobject[]optional

    Per-day availability rules.

  • offered_onlinebooleanoptional

    Whether the package is bookable via the public shopfront.

  • privatebooleanoptional

    When true, only customers with the direct link can book this package.

  • visibilitystringoptional

    Visibility override controlling who can see this package on the shopfront. Same semantics as on create.

    Possible values:publiclink_onlyprivate
  • customers_onlybooleanoptional

    Restrict booking to registered customers.

  • members_onlybooleanoptional

    Restrict booking to permitted membership-type holders.

  • permitted_membership_type_idsstring[]optionalnullable

    Membership types whose members can book when members_only=true.

  • membership_booking_windows_enabledbooleanoptional

    Whether to apply per-membership-type advance-booking windows.

  • membership_booking_windowsobject[]optional

    Per-membership-type advance-window overrides.

  • item_choicesobject[]optional

    Replacement set of item choices for this package. Same shape as PackageItemChoice on the Package schema.

  • upsell_offeringsobject[]optional

    Upsell candidates at booking confirmation.

  • cross_sell_offeringsobject[]optional

    Cross-sell candidates during booking.

  • category_idsstring[]optional

    Category IDs for shopfront grouping.

  • metaobjectoptional

    SEO metadata for the shopfront page.

  • customer_cancellation_permittedstringoptionalnullable

    Customer self-cancellation policy.

    Possible values:allowedif_unpaiddisallowed
  • customer_cancellation_min_durationstringoptionalnullable

    ISO 8601 duration before start at which cancellation is locked.

  • max_daily_durationintegeroptionalnullable

    Maximum minutes between first-item start and last-item end on each day.

  • max_advance_bookings_intervalstringoptionalnullable

    ISO 8601 maximum advance-booking duration.

  • min_advance_bookings_intervalstringoptionalnullable

    ISO 8601 minimum advance-booking duration.

  • min_guestsintegeroptionalnullable

    Minimum guests per booking.

  • max_guestsintegeroptionalnullable

    Maximum guests per booking. When either min_guests or max_guests is not exactly 2, separate_couples_package_choices is forced to false server-side.

  • prevent_choice_overlapsbooleanoptionalnullable

    Whether to prevent booking choices in this package from overlapping times.

  • separate_couples_package_choicesbooleanoptionalnullable

    For couples packages, whether each guest can independently pick choices. Forced to false for any other guest configuration.

  • image_idstringoptionalnullable

    ID of an uploaded Media to use as the cover image. Pass null to clear.

  • default_revenue_centrestringoptionalnullable

    Default revenue centre identifier to fall back to when balancing allocations. Must be a valid revenue centre at the package's site.

  • email_optionsobjectoptional

    Email-rendering options for this package.

  • overnight_package_configobjectoptional

    Overnight-package configuration. When enabled=true, both rate_id and num_nights must be set (either in this request or already on the package).

  • include_pricing_on_calendarbooleanoptional

    Surface prices in calendar views.

  • max_per_basketintegeroptionalnullable

    Max of this package per basket.

  • max_per_guestintegeroptionalnullable

    Max of this package per guest per basket.

Responses

  • 200

    A single Package.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

delete/shop/packages/{packageId}

Delete a package

deletePackage

Soft-deletes the package. Existing orders containing it are unaffected; the package is removed from new-booking flows. Use POST .../restore to bring it back.

Requires the SETTINGS_MANAGE permission on the package's site.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

Query parameters

  • basketItemIdobject-idoptional

    The ID of the basket item associated with the package. If provided, the returned package will include additional fields relevant to the basket item.

Responses

  • 204

    Package deleted successfully.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

post/shop/packages/{packageId}/copy

Duplicate a package

copyPackage

Creates a copy of an existing Package with new fields applied from the request body. Useful when seeding a new offering off an existing one rather than building from scratch. The new package is created under the same site and organisation as the original; fields not listed in the body are inherited from the source unchanged.

Requires the SETTINGS_MANAGE permission on the original package's site. As with create/update, separate_couples_package_choices is forced to false unless both min_guests and max_guests equal 2, and overnight_package_config.enabled=true requires rate_id and num_nights.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

Request body

  • namestringoptional

    Display name for the new copy. Strongly recommended so the copy is distinguishable from the source.

  • descriptionstringoptional

    Override the customer-facing long-form description on the copy. Defaults to the source's description when omitted. Markdown rendered.

  • external_idstringoptionalnullable

    Override external identifier on the copy. Defaults to null so integrations don't accidentally see two offerings with the same external id.

  • priceintegeroptional

    Flat base price (in the smallest currency unit, e.g. pence/cents) to set on the copy. Most packages prefer price_rules; this field is a convenience for the simple case.

  • currencystringoptional

    The ISO-4217 currency code.

  • availability_rulesobject[]optional

    Override the per-day availability rules on the copy.

  • offered_onlinebooleanoptional

    Whether the copy is bookable via the public shopfront. Defaults to the source's value.

  • privatebooleanoptional

    When true, only customers with the direct link can book the copy.

  • visibilitystringoptional

    Visibility override on the copy. Same semantics as on the source.

    Possible values:publiclink_onlyprivate
  • customers_onlybooleanoptional

    When true, only registered customers (not guests) can book the copy.

  • members_onlybooleanoptional

    When true, only members of permitted membership types can book the copy.

  • permitted_membership_type_idsstring[]optionalnullable

    Membership types whose members can book the copy when members_only=true.

  • membership_booking_windows_enabledbooleanoptional

    Whether to apply per-membership-type advance-booking windows on the copy.

  • membership_booking_windowsobject[]optional

    Per-membership-type advance-window overrides on the copy.

  • upsell_offeringsobject[]optional

    Override the upsell candidates surfaced at booking confirmation on the copy.

  • cross_sell_offeringsobject[]optional

    Override the cross-sell candidates surfaced during the booking flow on the copy.

  • metaobjectoptional

    SEO metadata for the copy's shopfront page.

  • customer_cancellation_permittedstringoptionalnullable

    Customer self-cancellation policy on the copy. allowed = always; if_unpaid = only if no payment has been taken; disallowed = never.

    Possible values:allowedif_unpaiddisallowed
  • customer_cancellation_min_durationstringoptionalnullable

    ISO 8601 duration before the package start during which cancellation is no longer permitted on the copy.

  • max_daily_durationintegeroptional

    Maximum minutes between first-item start and last-item end on each day for the copy.

  • max_advance_bookings_intervalstringoptionalnullable

    ISO 8601 duration limiting how far in advance customers can book the copy.

  • min_advance_bookings_intervalstringoptionalnullable

    ISO 8601 duration limiting how soon before the package start a customer can book the copy.

  • min_guestsintegeroptionalnullable

    Minimum guests per booking of the copy.

  • max_guestsintegeroptionalnullable

    Maximum guests per booking of the copy.

  • prevent_choice_overlapsbooleanoptional

    Whether to prevent booking choices in the copy from overlapping times.

  • separate_couples_package_choicesbooleanoptionalnullable

    For couples packages, whether each guest can independently pick choices on the copy. Forced to false for any other guest configuration.

  • email_optionsobjectoptional

    Email-rendering options for the copy.

  • overnight_package_configobjectoptional

    Overnight-package configuration on the copy. When enabled=true, both rate_id and num_nights are required.

  • include_pricing_on_calendarbooleanoptional

    Whether to surface the price alongside the copy in calendar views.

  • max_per_basketintegeroptionalnullable

    Maximum number of the copy per basket.

  • max_per_guestintegeroptionalnullable

    Maximum number of the copy per individual guest per basket.

Responses

  • 201

    A single Package.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

post/shop/packages/{packageId}/restore

Restore a deleted package

restorePackage

Un-deletes a previously soft-deleted Package. The package returns to its pre-deletion state, including price, item choices, availability rules, and overnight configuration. Existing orders that contained the package remain unaffected.

Requires the SETTINGS_MANAGE permission on the package's site. No request body.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

Responses

  • 200

    The package was restored successfully.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

get/shop/packages/{packageId}/availability-rules

List availability rules for a package

listPackageAvailabilityRules

Returns all AvailabilityRules configured on the given Package. Availability rules carve up the working calendar into windows when the package can or cannot be booked — useful for blocking holidays, restricting weekend hours, or making the package available only during specific seasons.

Rule semantics: any is_available: false rule overrides any is_available: true rule for the same time period. Results are paginated.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

Query parameters

  • pageintegeroptional

    The page to retrieve results from

  • per_pageintegeroptional

    The number of results to return per page

Responses

  • 200

    A paginated list of AvailabilityRules on a Package.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

post/shop/packages/{packageId}/availability-rules

Create an availability rule for a package

createPackageAvailabilityRule

Adds a new AvailabilityRule to a Package. With is_available: true the rule opens new bookable windows; with is_available: false it blocks them. Any false rule overrides any true rule for the same period. Omitting date/time/weekday filters means the rule applies always.

date_from defaults to today in the package's timezone when omitted. Requires the SETTINGS_MANAGE permission on the package's site.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

Request body

  • is_availablebooleanrequired

    When true, this rule opens bookable windows for the package. When false, it closes them. Any false rule overrides any true rule for the same time period.

  • date_fromdateoptionalnullable

    First date this rule applies (inclusive). Defaults to today in the package's timezone when omitted.

  • date_todateoptionalnullable

    Last date this rule applies (inclusive). When omitted, the rule has no end date.

  • time_fromstringoptionalnullable

    Start of the daily time window in 24-hour HH:MM format.

  • time_tostringoptionalnullable

    End of the daily time window in 24-hour HH:MM format.

  • min_durationintegeroptionalnullable

    Match the rule only when the package's total duration is ≥ this many minutes. Omit to apply to any duration.

  • max_durationintegeroptionalnullable

    Match the rule only when the package's total duration is ≤ this many minutes.

  • weekdaysstring[]optional

    Days of the week the rule applies on. Empty / omitted means every day.

Responses

  • 201

    A single AvailabilityRule belonging to a Package.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

get/shop/packages/{packageId}/availability-rules/{availabilityRuleId}

Retrieve a package availability rule

getPackageAvailabilityRule

Returns a single AvailabilityRule belonging to the given Package. Requires the SETTINGS_MANAGE permission on the package's site.

Path parameters

Responses

  • 200

    A single AvailabilityRule belonging to a Package.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

put/shop/packages/{packageId}/availability-rules/{availabilityRuleId}

Update a package availability rule

updatePackageAvailabilityRule

Replaces an AvailabilityRule on a Package. The server validates the same shape as on create, so is_available is required. Requires the SETTINGS_MANAGE permission on the package's site.

Path parameters

Request body

  • is_availablebooleanrequired

    Whether the window is bookable. false rules override true rules.

  • date_fromdateoptionalnullable

    First date this rule applies (inclusive).

  • date_todateoptionalnullable

    Last date this rule applies (inclusive).

  • time_fromstringoptionalnullable

    Daily start time in HH:MM.

  • time_tostringoptionalnullable

    Daily end time in HH:MM.

  • min_durationintegeroptionalnullable

    Match only for total package durations ≥ this many minutes.

  • max_durationintegeroptionalnullable

    Match only for total package durations ≤ this many minutes.

  • weekdaysstring[]optional

Responses

  • 200

    A single AvailabilityRule belonging to a Package.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

delete/shop/packages/{packageId}/availability-rules/{availabilityRuleId}

Delete a package availability rule

deletePackageAvailabilityRule

Removes an AvailabilityRule from a Package. Calendar availability is recomputed from the remaining rules. Existing bookings are unaffected. Requires the SETTINGS_MANAGE permission on the package's site.

Path parameters

Responses

  • 204

    Availability rule deleted successfully.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

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

List item choices on a package

listPackageItemChoices

Returns every PackageItemChoice configured on the given Package. Item choices are the building blocks of a package — each one defines a set of options the customer picks from (e.g. "Pick a 60-minute treatment", "Pick lunch or afternoon tea"). The package's overall price is the sum of the chosen options, with optional option_budget and price_change overrides per choice / option.

Order is preserved across reads — it reflects the customer-facing order in the booking flow, and can be modified through the reorder endpoint on the parent package.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

Responses

  • 200

    A list of PackageItemChoices configured on a Package.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

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

Create an item choice on a package

createPackageItemChoice

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.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

Request body

  • namestringoptional

    A short, customer-facing label for the choice.

  • descriptionstringoptionalnullable

    A longer explanation rendered alongside the options at booking time.

  • min_optionsintegeroptionalnullable

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

  • max_optionsintegeroptionalnullable

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

  • option_budgetintegeroptionalnullable

    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_timeslotbooleanoptional

    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_timesbooleanoptional

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

  • allocationobjectoptionalnullable

    An accounting allocation for this choice — splits the choice's portion of the package revenue into a named revenue centre at a fixed amount.

  • optionalbooleanoptional

    Whether the customer can skip this choice entirely.

  • visiblebooleanoptional

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

  • offering_typestringoptional

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

    Possible values:appointmentarea_bookinghotel_room_reservationproductsessiontable_reservation
  • optionsobject[]optional

    The list of selectable options. Each option references an offering on the package's site; the option's item_type must match this choice's offering_type.

Responses

  • 201

    A single PackageItemChoice on a Package.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

get/shop/packages/{packageId}/item-choices/{itemChoiceId}

Retrieve a package item choice

getPackageItemChoice

Returns a single PackageItemChoice belonging to the given Package, including the full option list and any configured start-time rules.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

  • itemChoiceIdobject-idrequired

    The unique identifier of the item choice (also known as a choice group) within the package.

Responses

  • 200

    A single PackageItemChoice on a Package.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

put/shop/packages/{packageId}/item-choices/{itemChoiceId}

Update a package item choice

updatePackageItemChoice

Updates a PackageItemChoice on a Package. Every field is optional; only the fields you send are written. Update is the only place where start_time_rules, allow_overlaps and choice_configuration can be set.

Setting visible: false is only valid when offering_type is product; other types return 400. When max_options becomes 1 any option_budget is dropped server-side. When the parent package's prevent_choice_overlaps is not true, allow_overlaps is forced to null.

Requires the SETTINGS_MANAGE permission on the package's site.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

  • itemChoiceIdobject-idrequired

    The unique identifier of the item choice (also known as a choice group) within the package.

Request body

  • namestringoptional

    A short, customer-facing label for the choice.

  • descriptionstringoptionalnullable

    A longer explanation rendered alongside the options at booking time.

  • min_optionsintegeroptional

    Minimum number of options the customer must pick.

  • max_optionsintegeroptionalnullable

    Maximum number of options the customer may pick. With max_options: 1 any option_budget is dropped.

  • option_budgetintegeroptionalnullable

    Included budget for the chosen options in the smallest currency unit.

  • auto_select_timeslotbooleanoptional

    Whether the booking engine should auto-pick a timeslot for this choice.

  • hide_timesbooleanoptional

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

  • allocationobjectoptionalnullable

    An accounting allocation for this choice. Send null fields to clear the existing allocation.

  • optionalbooleanoptional

    Whether the customer can skip this choice entirely.

  • visiblebooleanoptional

    Whether the choice is visible to the customer. Setting visible: false is only allowed when offering_type is product; other types return 400.

  • offering_typestringoptional

    The type of offerings this choice's options reference.

    Possible values:appointmentarea_bookinghotel_room_reservationproductsessiontable_reservation
  • start_time_rulesobject[]optional

    Rules restricting which start times are offered for this choice's options. Each rule is either absolute (fixed HH:MM window) or relative (offset in minutes from a base point such as the start of the package's first item).

  • allow_overlapsbooleanoptional

    Allow this choice's items to overlap with other items even when prevent_choice_overlaps is true on the parent package. Has no effect unless the package opts in to overlap prevention.

  • optionsobject[]optional

    The list of selectable options. At least one option is required unless offering_type is hotel_room_reservation. Each option's item_type must match offering_type.

  • choice_configurationobjectoptional

    Free-form additional configuration for the choice. Shape depends on offering_type.

Responses

  • 200

    A single PackageItemChoice on a Package.

  • 400

    The request failed.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

delete/shop/packages/{packageId}/item-choices/{itemChoiceId}

Delete a package item choice

deletePackageItemChoice

Removes a PackageItemChoice from a Package. The remaining choices keep their order. Existing bookings of the package are unaffected. Requires the SETTINGS_MANAGE permission on the package's site.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

  • itemChoiceIdobject-idrequired

    The unique identifier of the item choice (also known as a choice group) within the package.

Responses

  • 204

    Item choice deleted successfully.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

get/shop/packages/{packageId}/price-rules

List price rules for a package

listPackagePriceRules

Returns all PriceRules configured on the given Package. Price rules determine the price the customer pays based on when the package is booked — peak vs off-peak, weekday vs weekend, seasonal overrides. The first rule whose conditions match the booking wins; when no rule matches, the package falls back to a sensible default.

Results are paginated. Requires read access to the package's site.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

Query parameters

  • pageintegeroptional

    The page to retrieve results from

  • per_pageintegeroptional

    The number of results to return per page

Responses

  • 200

    A paginated list of price rules for a package.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

post/shop/packages/{packageId}/price-rules

Create a price rule for a package

createPackagePriceRule

Adds a new PriceRule to a Package. Combine date ranges, time windows and weekday filters to express most pricing scenarios — peak vs off-peak, weekday vs weekend, seasonal overrides. The first rule whose conditions match a given booking wins. Sending no filters creates a fallback "always applies" rule.

date_from defaults to today in the site's timezone when omitted. Requires the SETTINGS_MANAGE permission on the package's site.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

Request body

  • priceintegerrequired

    Price in the smallest currency unit (e.g. pence, cents). 20000 means £200.00 in a GBP-denominated site.

  • date_fromdateoptionalnullable

    First date this rule applies (inclusive). Defaults to today in the site's timezone when omitted.

  • date_todateoptionalnullable

    Last date this rule applies (inclusive). When omitted, the rule has no end date.

  • time_fromstringoptionalnullable

    Start of the time-of-day window in 24-hour HH:MM format. When time_to is set, must be earlier than time_to (the rule does not wrap past midnight).

  • time_tostringoptionalnullable

    End of the time-of-day window in 24-hour HH:MM format. Must be later than time_from if both are set.

  • weekdaysstring[]optional

    Days of the week this rule applies on. Empty / omitted means every day.

Responses

  • 201

    A single PriceRule belonging to a Package.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

get/shop/packages/{packageId}/price-rules/{priceRuleId}

Retrieve a package price rule

getPackagePriceRule

Returns a single PriceRule belonging to the given Package. Requires read access to the package's site.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

  • priceRuleIdobject-idrequired

    The unique identifier of the price rule.

Responses

  • 200

    A single PriceRule belonging to a Package.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

put/shop/packages/{packageId}/price-rules/{priceRuleId}

Update a package price rule

updatePackagePriceRule

Replaces a PriceRule on a Package. The server validates the same shape as on create, so price is required. Requires the SETTINGS_MANAGE permission on the package's site.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

  • priceRuleIdobject-idrequired

    The unique identifier of the price rule.

Request body

  • priceintegerrequired

    Price in the smallest currency unit.

  • date_fromdateoptionalnullable

    First date this rule applies (inclusive).

  • date_todateoptionalnullable

    Last date this rule applies (inclusive).

  • time_fromstringoptionalnullable

    Start of the time-of-day window in HH:MM.

  • time_tostringoptionalnullable

    End of the time-of-day window in HH:MM.

  • weekdaysstring[]optional

Responses

  • 200

    A single PriceRule belonging to a Package.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

delete/shop/packages/{packageId}/price-rules/{priceRuleId}

Delete a package price rule

deletePackagePriceRule

Removes a PriceRule from a Package. Existing bookings priced under this rule are unaffected — they retain the price recorded at booking time. Requires the SETTINGS_MANAGE permission on the package's site.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

  • priceRuleIdobject-idrequired

    The unique identifier of the price rule.

Responses

  • 204

    Price rule deleted successfully.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

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

Reorder a package's item choice groups

actionReorderPackageItemChoices

Reorders the item_choices groups on a Package to match the supplied sequence of group IDs. Pass every existing item_choices[].id exactly once in the desired display order.

IDs not included in the order array are pushed to the tail in their original relative order, so a partial reorder simply moves the listed IDs to the front. Unknown IDs are ignored.

Returns the freshly-sorted Package. Requires the SETTINGS_MANAGE permission on the package's site.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

Request body

  • orderstring[]required

    The desired sequence of item-choice group IDs. IDs not listed are appended to the tail in their existing relative order. Unknown IDs are silently ignored.

Responses

  • 200

    A single Package.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

get/shop/packages/{packageId}/item-choices/{itemChoiceId}/options

List options for a package item choice

listPackageItemChoiceOptions

Returns every PackageItemChoiceOption configured on the named PackageItemChoice. Each option names a specific offering (e.g. a particular appointment type or retail product) that the parent choice may be filled by, plus the price uplift the option carries.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

  • itemChoiceIdobject-idrequired

    The unique identifier of the item choice (also known as a choice group) within the package.

Responses

  • 200

    A list of PackageItemChoiceOptions on a PackageItemChoice.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

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

Add an option to a package item choice

createPackageItemChoiceOption

Adds a new PackageItemChoiceOption to the parent PackageItemChoice. The body sets the offering the option points at and any price uplift; the option is appended to the choice's existing list.

Requires the SETTINGS_MANAGE permission on the package's site.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

  • itemChoiceIdobject-idrequired

    The unique identifier of the item choice (also known as a choice group) within the package.

Request body

  • idstringrequired

    Identifier of the offering this option points at — an AppointmentType, SessionType or retail Product, depending on item_type. The guest sees the offering's name and image when picking this option in the storefront.

  • item_typestringrequired

    The type of item this option represents.

  • offeringobjectrequirednullable
  • price_changeintegerrequirednullable

    A currency amount that this option would increase the package price by.

Responses

  • 201

    A single PackageItemChoiceOption.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

get/shop/packages/{packageId}/item-choices/{itemChoiceId}/options/{optionId}

Get a package item choice option

getPackageItemChoiceOption

Returns a single PackageItemChoiceOption on the named PackageItemChoice.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

  • itemChoiceIdobject-idrequired

    The unique identifier of the item choice (also known as a choice group) within the package.

  • optionIdobject-idrequired

    The unique identifier of the PackageItemChoiceOption — one of the offerings exposed by the parent PackageItemChoice as a pickable slot in the package.

Responses

  • 200

    A single PackageItemChoiceOption.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

put/shop/packages/{packageId}/item-choices/{itemChoiceId}/options/{optionId}

Update a package item choice option

updatePackageItemChoiceOption

Updates the offering or price uplift on an existing PackageItemChoiceOption. Fields omitted from the body are left unchanged.

Requires the SETTINGS_MANAGE permission on the package's site.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

  • itemChoiceIdobject-idrequired

    The unique identifier of the item choice (also known as a choice group) within the package.

  • optionIdobject-idrequired

    The unique identifier of the PackageItemChoiceOption — one of the offerings exposed by the parent PackageItemChoice as a pickable slot in the package.

Request body

  • idstringrequired

    Identifier of the offering this option points at — an AppointmentType, SessionType or retail Product, depending on item_type. The guest sees the offering's name and image when picking this option in the storefront.

  • item_typestringrequired

    The type of item this option represents.

  • offeringobjectrequirednullable
  • price_changeintegerrequirednullable

    A currency amount that this option would increase the package price by.

Responses

  • 200

    A single PackageItemChoiceOption.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

delete/shop/packages/{packageId}/item-choices/{itemChoiceId}/options/{optionId}

Delete a package item choice option

deletePackageItemChoiceOption

Removes a PackageItemChoiceOption from its parent PackageItemChoice. Existing bookings of the package are unaffected; the option is just hidden from the choice's available options going forward. Requires the SETTINGS_MANAGE permission on the package's site.

Path parameters

  • packageIdobject-idoptional

    The ID of the package

  • itemChoiceIdobject-idrequired

    The unique identifier of the item choice (also known as a choice group) within the package.

  • optionIdobject-idrequired

    The unique identifier of the PackageItemChoiceOption — one of the offerings exposed by the parent PackageItemChoice as a pickable slot in the package.

Responses

  • 204

    The option was successfully deleted.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found