# Stoplight published URL: https://docs.roller.app/docs/api/rest openapi: 3.1.0 info: title: REST API version: 1.0.0 description: '' contact: name: ROLLER Help Centre url: 'https://mysupport.roller.software/' termsOfService: 'https://www.roller.software/terms' servers: - description: Production url: 'https://api.roller.app' - url: 'https://api.play.roller.app' description: Playground (Test Environment) tags: - name: Booking Information description: Search for bookings and retrieve the detail of a single booking. - name: Booking Management description: 'Create, update, cancel, and delete bookings, including draft bookings.' - name: Capacity Reservation description: 'Reserve and release product capacity, and manage resource capacity blocks.' - name: Company description: Retrieve and update venue company profiles. - name: Discount description: 'Create, retrieve, and update discounts, and manage discount codes.' - name: Gift Card description: Create gift cards and check gift card balances. - name: Guest description: 'Retrieve and update guest records, multi-passes, and signed waivers.' - name: Modifier description: 'List, retrieve, create, and update modifier groups.' - name: Price Rule description: Retrieve the configuration of time-based price rules. - name: Product description: 'Retrieve product availability and product detail, and manage stock products.' - name: Redemption description: Redeem tickets against a booking. - name: Segments description: Retrieve the guest segments configured for the venue. - name: Staff description: 'Create, retrieve, update, and delete staff accounts. Lock, unlock, and send email invitations to staff members.' - name: Transaction description: 'Record payments, refunds, and tips against bookings, calculate booking costs, and manage payment links.' - name: Venue Information description: Retrieve detail about the authenticated venue. - name: Webhooks description: Webhooks paths: /product-availability: get: tags: - Product summary: Get product availability description: |- Returns products available for a specific date. This includes capacity and session time information where supported. > Availability depends on a number of factors: > * **Dates** defined on the product, **times** defined in **schedules**, and **exclusion periods** > * **Sale periods**, including **cut-off settings** > * Capacity, which may be fixed/unlimited **quantity** or depend on **resource** settings > * What the **product type** is, such as stock, session or party package > * ...And other settings like `Hide from online sales` > For more information on availability, please see our [**help centre**](https://mysupport.roller.software/hc/en-us/articles/6442667452431-Why-is-a-standard-pass-not-available-in-my-online-checkout). parameters: - name: Date in: query description: The date (yyyy-MM-dd) availability is needed for required: true schema: type: string example: '2025-07-14' format: date allowReserved: false - name: ProductCategory in: query description: Optional filter to get availability only for products in this product category schema: type: string example: Merchandise - name: ProductIds in: query description: Optional filter to get availability only for the parent product IDs in this comma separated list schema: type: string example: '107392,107399,107412' responses: '200': description: Successful content: application/json: schema: type: array items: type: object additionalProperties: false properties: parentProductId: type: string example: '107399' description: Parent product ID parentProductName: type: string description: Parent product name maxLength: 75 example: Season Pass type: $ref: ../models/ProductType.yaml description: type: string description: Brief description of the product maxLength: 150 example: Grants entry for the entire summer season imageUrl: type: string description: Product image URL example: 'https://someimage.com/10002' products: type: array items: $ref: ../models/ProductInfo.yaml availabilities: type: array items: $ref: ../models/ProductAvailability.yaml sessions: type: array items: $ref: ../models/ProductSession.yaml id: type: string description: Product ID (This has been replaced by `parentProductId`) example: '107399' deprecated: true name: type: string description: Product name (This has been replaced by `parentProductName`) maxLength: 75 example: Season Pass deprecated: true operationId: get-product-availability /product-availability/calendar: get: tags: - Product summary: Get product availability calendar description: |- Returns the availability status for each day in a given month for a single product. Designed for use in date picker and calendar UIs in third-party checkouts, allowing guests to see at a glance which dates have availability before selecting a specific date. Once the guest has selected a date, call [**Get product availability**](#/paths/~1product-availability/get) to retrieve session-level detail and capacity for that date. > Response data is cached for 1 minute and is invalidated when a new booking is created. operationId: get-product-availability-calendar parameters: - name: productId in: query required: true description: The ID of the product to retrieve calendar availability for schema: type: integer example: 107399 - name: date in: query required: true description: 'The month to retrieve availability for, in `YYYY-MM` format' schema: type: string example: 2026-07 responses: '200': description: Successful content: application/json: schema: type: array description: One entry for each day in the requested month items: $ref: ../models/ProductAvailabilityCalendarDay.yaml '404': description: Product not found /products: get: tags: - Product summary: Get product detail parameters: - name: ProductCategory in: query description: Optional filter to get availability only for products in this product category schema: type: string example: Merchandise - schema: type: string example: Pass in: query name: productType description: 'Optionally filter by product type. See [**product type mapping**](https://docs.roller.app/docs/api/product-type-mapping).' - schema: type: string example: Membership in: query name: productSubType description: 'Optionally filter by product sub type. See [**product type mapping**](https://docs.roller.app/docs/api/product-type-mapping).' responses: '200': description: Successful content: application/json: schema: type: array items: type: object properties: parentProductId: type: string example: '107399' maxLength: 150 description: Parent product ID parentProductName: type: string example: Season Pass maxLength: 75 description: Parent product name type: $ref: ../models/ProductType.yaml stockProductType: $ref: ../models/StockProductType.yaml products: type: array items: $ref: ../models/SaleProduct.yaml shortDescription: type: string description: Brief description of the product example: Grants entry for the entire summer season maxLength: 150 description: type: string description: Longer form product description example: 'Grants entry for the entire summer season. Access includes all rides, events, and 1 free drink per guest per day' maxLength: 4000 imageUrl: type: string description: Product image URL example: 'https://someimage.com/10002' termsAndConditionsText: type: string description: Custom terms and conditions for the parent product example: All participants must follow staff instructions at all times. addOns: type: array description: The add-on product IDs linked to this product items: type: string description: Product IDs of add on/stock products which are to be offered as up sells when purchasing this product example: '107383' validDays: type: - integer - 'null' description: The number of days a pass is valid from date of purchase example: 90 validDaysFromRedemption: type: - integer - 'null' description: The number of days a pass is valid from date of redemption example: 1 restrictedAddOns: type: array description: The restricted add-ons linked to this product items: type: object properties: stockPeriodId: type: integer addOns: type: array items: type: string days: type: array items: type: object properties: closed: type: boolean timeRanges: type: array items: type: object properties: startTime: type: string format: time endTime: type: string format: time formIds: type: array description: The form IDs linked to this product items: type: string example: d4ad7af49a9b435 tags: type: array description: Tags associated with this product items: type: string description: Product IDs of add on/stock products which are to be offered as up sells when purchasing this product example: '"Admission"' minPurchase: type: integer example: 1 description: Minimum product purchase priceRuleId: type: - string - 'null' format: uuid description: 'ID of the price rule applied to this product, if any. The prices each ticket type charges under the rule are returned in `priceRule` on each item in `products`. For a `time` rule, use [**Get price rules**](#/paths/~1price-rules/get) for the tiers and when each one applies. See [**Price rules**](https://docs.roller.app/docs/api/price-rules).' example: 22f29d68-1c94-4de2-b616-020108d92a06 pricingRuleId: type: - string - 'null' format: uuid description: 'Pricing rule identifier that links the product to a custom pricing rule, for session pass type products. (This has been replaced by `priceRuleId`)' example: 22f29d68-1c94-4de2-b616-020108d92a06 deprecated: true depositPercentage: type: number description: The minimum percentage of the product cost required for purchase. Only one of `depositPercentage` or `depositAmount` should be used. example: 25 depositAmount: type: number description: The minimum amount required for purchase. Only one of `depositPercentage` or `depositAmount` should be used. example: 12 modifiers: type: array description: The booking cost modifier IDs linked to this product items: type: string description: Product IDs of linked modifiers that can optionally be added to this product example: 988835b8-d64e-4369-96cb-caaa20a7396c modifierGroups: type: array description: The booking cost modifier groups linked to this product items: type: object properties: id: type: integer name: type: string isRequired: type: boolean isSingleChoice: type: boolean isOpenQuantity: type: boolean displayName: type: string modifiers: type: array items: type: object properties: id: type: string format: uuid amount: type: - number - 'null' percentage: type: - number - 'null' name: type: string description: type: string termsAndConditions: type: string imageUrl: type: string isRequiredForOnlinePurchase: type: boolean isDefault: type: boolean defaultQuantity: type: string example: '2' giftcard: type: object description: Configuration detail for gift card products properties: canSendDigital: type: boolean canSendPhysical: type: boolean supportsVideoMessage: type: boolean supportsWrittenMessage: type: boolean pickupAvailable: type: - boolean - 'null' messagingOptionLimit: type: - integer - 'null' pickupDescription: type: string productPostages: type: array items: type: object properties: productPostageId: type: string type: type: string price: type: number description: type: string partyDetails: type: object description: Configuration for additional party details to be captured in progressive checkouts for party package type products properties: partyNamePrompt: type: string description: Phrase used to request party name when a party package type product is being purchased via progressive checkouts example: Please provide a name that describes your party and includes the guest of honour guestListEnabled: type: boolean description: Whether guest list feature is enabled. Requires that `partyNamePrompt` is used. agreement: type: object description: Determines the booking agreement the guest needs to sign for this product properties: bookingAgreementId: type: integer example: 4 description: Booking agreement ID formIdentifier: type: string example: d4ad7af49a9b435 description: Form ID isWaiverRequired: type: boolean description: Determines whether the guest needs to sign a waiver for this product captureTicketHolderName: type: boolean description: Whether names of each ticket holder are requested when items are purchased via progressive checkouts duration: type: - integer - 'null' description: Duration of the time-based product in minutes example: 90 durationType: enum: - PerSession - PerGuest description: Determines whether duration is based on session or guest count meta: type: array description: Meta values for the product items: type: object additionalProperties: type: string example: value id: type: string description: Product ID (This has been replaced by `parentProductId`) example: '107399' deprecated: true name: type: string description: Product name (This has been replaced by `parentProductName`) example: Season Pass maxLength: 75 deprecated: true description: |- Returns product information for a venue. > Changes in this data are not expected to change frequently. As such data must be cached and this endpoint used sparingly. > Detail includes when the product is offered, but calls should be made to [**get product availability**](#/paths/~1product-availability/get) to determine if there's capacity on a given day. operationId: get-product-detail /products/stock: post: summary: Create stock products tags: - Product responses: '200': description: OK content: application/json: schema: $ref: ../models/UpdateProductStock.yaml operationId: create-stock-products requestBody: content: application/json: schema: $ref: ../models/CreateProductStock.yaml description: Create a stock product put: summary: Update stock products tags: - Product responses: '200': description: OK content: application/json: schema: $ref: ../models/UpdateProductStock.yaml operationId: update-stock-products requestBody: content: application/json: schema: $ref: ../models/UpdateProductStock.yaml description: "Update an existing stock product by editing details or creating new variations. \r\n\r\n> 1. Ensure all field values (Including those that aren't being updated) are in the request otherwise they will be overwritten to be empty\r\n> 2. To update an existing variation, the child/variation level `productId` is required.\r\n> 3. To create a new variation, the child/variation level `externalId` is required (with no `productId`)." '/products/stock/{parentProductId}/quantity': put: summary: Update stock quantity tags: - Product responses: '200': description: OK content: application/json: schema: $ref: ../models/UpdateProductStock.yaml operationId: update-stock-quantity requestBody: content: application/json: schema: type: object required: - productId properties: productId: type: integer description: Unique `productId` of the child product example: 245252 quantity: type: - integer - 'null' description: The new quantity of the product minimum: 0 format: int32 x-internal: false description: "Update an existing stock product by editing the quantity.\r\n\r\n* Setting `quantity` to `null` will set the stock quantity to **unlimited**\r\n* `quantity` cannot be set to `null` if `parLevel` is not set to zero (`0`) \r\n" parameters: - $ref: '#/components/parameters/parentProductId' /price-rules: get: tags: - Price Rule summary: Get price rules responses: '200': description: Successful content: application/json: schema: type: array items: $ref: ../models/PriceRuleDetail.yaml description: |- Returns the active time-based price rules configured for the venue. Each rule describes the tiers a product can be priced at and when each tier applies, as recurring days of the week with optional times of day, and override date ranges. The price each ticket type charges for a tier is not returned here. It is returned as `priceRule.timeTiers` on each ticket type by [**Get product detail**](#/paths/~1products/get). Join the two on `priceRuleId`, then match tiers on `tierId`. If a tier has no entry in `timeTiers`, the ticket type's base `price` applies. Every other type of price rule (`quantity`, `earlyBird` and `capacity`) is described in full by **Get product detail** and is not returned here. See [**Price rules**](https://docs.roller.app/docs/api/price-rules) for how each type is applied. > Changes in this data are not expected to be frequent. As such data must be cached and this endpoint used sparingly. operationId: get-price-rules /modifiers: get: tags: - Modifier summary: List modifier groups description: Returns the venue's modifier groups and their modifiers. Optionally filter by name with `keywords`, or to the groups linked to a stock product with `productId`. parameters: - name: keywords in: query required: false schema: type: string description: Filter to modifier groups whose name contains this text - name: productId in: query required: false schema: type: integer description: Filter to modifier groups linked to this stock product responses: '200': description: Successful content: application/json: schema: type: array items: $ref: ../models/ModifierGroup.yaml operationId: list-modifier-groups post: tags: - Modifier summary: Create modifier group description: Creates a modifier group, its modifiers, and the stock products it is linked to. requestBody: content: application/json: schema: $ref: ../models/ModifierGroupRequest.yaml responses: '200': description: Successful content: application/json: schema: $ref: ../models/ModifierGroup.yaml operationId: create-modifier-group '/modifiers/{groupId}': get: tags: - Modifier summary: Get modifier group description: Returns a single modifier group and its modifiers. responses: '200': description: Successful content: application/json: schema: $ref: ../models/ModifierGroup.yaml '404': description: Modifier group not found operationId: get-modifier-group put: tags: - Modifier summary: Update modifier group description: 'Replaces an existing modifier group with the definition supplied. Modifiers sent with an existing `id` are updated; those sent without one are created.' requestBody: content: application/json: schema: $ref: ../models/ModifierGroupRequest.yaml responses: '200': description: Successful content: application/json: schema: $ref: ../models/ModifierGroup.yaml '404': description: Modifier group not found operationId: update-modifier-group parameters: - $ref: '#/components/parameters/groupId' /capacity-reservation: post: tags: - Capacity Reservation summary: Validate and reserve capacity responses: '200': description: The unique capacity reservation Id content: application/json: schema: type: object properties: uniqueId: type: string description: The unique capacity reservation Id example: ffdae420-a912-4d93-9234-9faca5e6194f '409': description: Invalid Reservation content: application/json: schema: type: object properties: errors: type: array items: type: object properties: name: type: string description: Name of the error example: LocationFullyBooked message: type: string description: Error message example: 'Fully booked on 10 Aug, 9:00 AM' requestBody: content: application/json: schema: type: object required: - items properties: items: type: array description: 'The products being purchased, known as booking items' items: $ref: ../models/BookingCreateItem.yaml description: |- > Validate and reserve capacity prior to creating a booking. > This endpoint is used to ensure there is no double booking of capacity within ROLLER. operationId: validate-and-reserve-capacity '/capacity-reservation/{uniqueId}': delete: tags: - Capacity Reservation summary: Delete a capacity reservation responses: '200': description: Deleted successfully '400': description: Invalid request description: |- > Delete a capacity reservation. > Use this endpoint to clear out existing reserved capacity so other customers may book. > Capacity reservations that are not deleted will automatically expire after 10 minutes. operationId: delete-a-capacity-reservation parameters: - $ref: '#/components/parameters/uniqueId' /capacity-reservation/block: post: tags: - Capacity Reservation summary: Block resource capacity responses: '200': description: The unique resource capacity block ID. content: application/json: schema: type: object properties: resourceCapacityBlockId: type: integer description: The unique resource capacity block ID example: 5516 '409': description: "* Resource could not be found\r\n* Resource will go over available capacity\r\n* Resource already booked or blocked out " requestBody: content: application/json: schema: type: object required: - resourceId - blockoutCapacity - date properties: resourceId: type: integer description: The ID of the resource being blocked blockoutCapacity: type: integer description: The total capacity to block out date: type: string format: date description: The date of the capacity block (In ISO8601 date format only) startTime: type: string description: "Start time in 24h format \r\n\r\n* eg: 00:00 = 12:00 AM (Midnight)\r\n* eg: 23:59 = 11:59 PM\r\n\r\nRequired if `blockEntireDay` is `false`" endTime: type: string description: "End time in 24h format \r\n\r\n* eg: 00:00 = 12:00 AM (Midnight)\r\n* eg: 23:59 = 11:59 PM\r\n\r\nRequired if `blockEntireDay` is `false`" blockEntireDay: type: boolean description: Boolean indicating if the block applies to the entire day notes: type: string description: Additional notes or reason for the block description: '> Block capacity for the specified resource.' operationId: block-resource-capacity get: summary: Search resource capacity blocks tags: - Capacity Reservation responses: '200': description: A list of resource capacity blocks content: application/json: schema: type: array items: $ref: ../models/ResourceCapacityBlock.yaml operationId: search-resource-capacity-blocks description: '> Search for existing resource capacity blocks.' parameters: - in: query description: The optional date for which to retrieve capacity blocks in ISO8601 format (`yyyy-MM-dd`) name: date schema: example: '2025-07-14' - schema: type: string example: '30539' in: query name: resourceId description: The optional ID of the resource to filter by '/capacity-reservation/block/{blockId}': parameters: - $ref: '#/components/parameters/blockId' delete: summary: Delete resource capacity block tags: - Capacity Reservation responses: '200': description: Capacity block successfully deleted. '404': description: Resource capacity block not found. operationId: delete-resource-capacity-block description: '> Delete an existing resource capacity block.' get: summary: Get resource capacity block tags: - Capacity Reservation responses: '200': description: A resource capacity block content: application/json: schema: $ref: ../models/ResourceCapacityBlock.yaml '404': description: Resource capacity block not found operationId: get-resource-capacity-block description: '> Get an existing resource capacity block.' /bookings: post: summary: Create a booking responses: '201': description: Booking identifiers content: application/json: schema: type: object properties: bookingReference: type: string description: The booking reference exposed within ROLLER and what the customer receives example: '77465528' uniqueId: type: string description: The bookings unique identifier example: 79189348-70fe-4347-bc0f-8887df841a3a '409': description: Invalid Booking content: application/json: schema: type: object properties: errors: type: array items: type: object properties: name: type: string description: Name of the error example: VenueCapacity message: type: string description: Error message example: Venue capacity will be exceeded requestBody: content: application/json: schema: type: object required: - externalId - customer - items properties: externalId: type: string description: 3rd party booking reference example: UJJSK28374 maxLength: 64 name: type: string description: Title of the booking. Name can be different to the booking owner name (defaults to the booking owner's name if not specified) example: Sports Group Booking maxLength: 128 comments: type: string description: Additional detail about the booking example: Customer has not visited before maxLength: 500 purchaseDate: type: - string - 'null' description: Optionally provide the creation datetime in UTC - generally used when re-creating bookings and needing to retain the original datetime example: '2020-07-29T06:57:18.5306035+00:00' format: date-time capacityReservationId: type: - string - 'null' description: The GUID returned from the capacity reservation API - it's recommended to use the capacity reservation API otherwise the request may be rejected example: c07128c8-adb1-45a0-9241-dc3875518468 companyId: type: - integer - 'null' description: Id of the company making the booking example: 12345 customer: $ref: ../models/BookingCreateCustomer.yaml description: 'The booking owner, i.e. the primary contact or person who paid for the booking' items: type: array description: 'The products being purchased, known as booking items' items: $ref: ../models/BookingCreateItem.yaml payments: type: array description: 'Any initial payments for the booking (the booking can be unpaid, partially paid or fully paid)' items: $ref: ../models/PaymentCreate.yaml discounts: type: array description: Any discount codes or custom discounts applied to the booking items: $ref: ../models/BookingCreateDiscount.yaml giftCards: type: array description: Any gift cards applied to the booking for paying down the booking subtotal. These payments do not need to cover the whole cost. items: $ref: ../models/BookingCreateGiftCard.yaml sendConfirmations: type: boolean description: When true ROLLER will send the booking confirmation / tickets to the customer automatically example: false customerPaysFees: type: boolean description: When true fees setup in ROLLER are applied. Please note if manual `creditCardFees` are provided in the request it will override all fees setup in ROLLER. default: false posNotes: type: string description: Additional detail when processing a booking from POS automaticCancelHours: type: - integer - 'null' example: 1 description: 'The number of hours until the booking will auto-expire, used to create a tentative booking. Leave empty if unused. ' metadata: type: object description: 'User-defined key-value pairs to store against the booking. Supports up to 20 entries. Keys are case-sensitive strings (max 40 characters). Values are strings (max 500 characters, HTML stripped on write).' additionalProperties: type: string example: reservationSource: partner-portal groupId: '881234' description: '' description: "Create a booking in ROLLER, and optionally add an associated payment record.\r\n\r\n> **Guest Records**\r\n> * Values provided in the `customer` object will create a **Guest** record\r\n> * This Guest record will be automatically attached to the booking as the **booking holder**\r\n> * An existing Guest record will be used where a match is found on `email`\r\n> * Where a match is found and other fields on the record are different, they will be updated to reflect the new value" operationId: create-a-booking tags: - Booking Management get: summary: Search for bookings description: "Returns basic booking detail for up to 100 of the most recent bookings based on search criteria.\r\n\r\n> At least one search criteria query parameter is required." parameters: - name: keywords in: query description: 'Keywords will search on `Booking Name`, `Ticket ID`, `Custom Ticket ID`, guest `First name`, `Last name`, `Email` and `Phone`. ' schema: type: string example: Andrew Smith - name: date in: query description: Booking date of booking items on the booking schema: type: string example: '2025-07-14' format: date - name: startTime in: query description: Session start time (only applies to session products) in 24hr format schema: type: string example: '14:00' - name: productIds in: query description: Comma separated product IDs. Date is required when using this parameter. schema: type: string example: '23882991' - name: locationIds in: query description: Comma separated resource IDs (formerly location IDs). Returns bookings with products capable of using these resources. Date is required when using this parameter. schema: type: string example: '27366' responses: '200': description: Booking detail content: application/json: schema: type: object properties: bookings: type: array items: $ref: ../models/BookingBasicDetail.yaml operationId: search-for-bookings tags: - Booking Information /bookings/draft/costs: post: summary: Get booking costs responses: '200': description: Bookings Costs content: application/json: schema: type: object properties: bookingCosts: type: object properties: subTotal: type: number description: Subtotal cost of all booking items example: 22 amountOwing: type: number description: The amount currently owing on the booking example: 21.87 discount: type: number description: Total amount of discounts on the booking (discounts are already factored into booking totals). example: 2.2 subTotalTax: type: number description: Total amount of tax on subtotal example: 1.8 feeTax: type: number description: Total amount of tax on fees example: 0.19 tax: type: number description: Total amount of tax example: 1.99 taxExclusive: type: number description: The value of items in the booking which have tax exclusive prices example: 0 transactionFee: type: number description: Total transaction fees on the booking example: 1.43 cardFee: type: number description: Credit card fees on the booking example: 0.64 productFee: type: number description: Total product fees on the booking example: 1.5 productFees: type: array description: The product fee rules charged on the booking items: type: object properties: productFeeId: type: integer description: Identifier of the product fee rule example: 42 name: type: string description: Name of the product fee example: Booking fee description: type: string description: Description of the product fee example: Applied to online bookings amount: type: number description: Fee amount charged on the booking example: 1.5 fees: type: number description: Total Fees (Service Fees) (i.e. Transaction Fees + Card Fees) example: 2.07 totalExcludingFees: type: number description: Total booking cost excluding fees payable by the customer example: 19.8 total: type: number description: Total booking cost including taxes and fees example: 21.87 totalIgnoringDeposit: type: number description: Total booking cost ignoring any deposit amount payable example: 21.87 discounts: type: array items: type: object properties: discount: type: number description: discount amounts for this discount code example: 2.2 code: type: string description: Discount code used on the booking example: AN829910 discounteditems: type: array items: type: object properties: itemNumber: type: string description: Unique reference for the specific discounted item in the booking example: c7585bf9-cdbe-433a-8ab9-a4260d9ebbca discount: type: number description: Value of the discount against this specific item example: 2.2 items: type: array description: Per-item cost breakdown for the booking items: type: object properties: uniqueId: type: string format: uuid description: Unique reference for this item in the booking example: c7585bf9-cdbe-433a-8ab9-a4260d9ebbca productId: type: integer description: Product ID of the item example: 153444 quantity: type: integer description: Quantity of the product example: 2 unitCost: type: number description: Cost of a single unit example: 11 totalCost: type: number description: Total cost for the quantity example: 22 giftCards: type: array items: type: object properties: giftCardNumber: type: string description: Gift Card number being redeemed example: '8839920172' amountDeducted: type: number description: Dollar value being deducted from the gift card when this booking is published example: 20 giftCardErrors: type: array items: type: string description: Error message/s for gift card/s redeemed example: Could not find giftcard for number 8839920172 '409': description: Invalid Booking content: application/json: schema: type: object properties: errors: type: array items: type: object properties: name: type: string description: Name of the error example: VenueCapacity message: type: string description: Error message example: Venue capacity will be exceeded requestBody: content: application/json: schema: type: object required: - externalId - customer - items properties: externalId: type: string description: 3rd party booking reference example: UJJSK28374 maxLength: 64 name: type: string description: Title of the booking. Name can be different to the booking owner name (defaults to the booking owner's name if not specified) example: Sports Group Booking maxLength: 128 comments: type: string description: Additional detail about the booking example: Customer has not visited before maxLength: 500 purchaseDate: type: - string - 'null' description: Optionally provide the creation datetime in UTC - generally used when re-creating bookings and needing to retain the original datetime example: '2020-07-29T06:57:18.5306035+00:00' capacityReservationId: type: - string - 'null' description: The GUID returned from the capacity reservation API - it's recommended to use the capacity reservation API otherwise the request may be rejected example: c07128c8-adb1-45a0-9241-dc3875518468 companyId: type: - integer - 'null' description: Id of the company making the booking example: 12345 customer: $ref: ../models/BookingCreateCustomer.yaml items: type: array items: $ref: ../models/BookingCreateItem.yaml payments: type: object description: 'The initial payments for the booking (the booking can be unpaid, partially paid or fully paid)' properties: id: type: string maxLength: 32 description: Payment or transaction Id paymentType: description: The payment type enum: - '' - CreditCard - CreditCardPreAuth - Cash - Cheque - BankTransfer - Other amount: type: number description: Total payment including fees in the venue's currency creditCardFees: type: number description: Credit card fees associated with the payment transactionFees: type: number description: Transaction or product fees associated with the payment (do not include credit card fees) discounts: type: array items: type: object properties: code: type: string description: Discount code being used on the booking (can apply multiple) example: AN829910 giftCards: type: array items: type: object properties: giftCardNumber: type: string description: Discount code being used on the booking (can apply multiple) example: '8839920172' sendConfirmations: type: boolean description: When true ROLLER will send the booking confirmation / tickets to the customer automatically example: false customerPaysFees: type: boolean description: When true fees setup in ROLLER are applied. Please note if manual `creditCardFees` are provided in the request it will override all fees setup in ROLLER. example: false default: false description: '' description: '> Provide a draft booking request and receive associated booking cost information. This will not actually create a draft booking, only provide relevant booking costs.' operationId: get-booking-costs tags: - Transaction /bookings/draft: post: summary: Create draft booking responses: '200': description: Draft Booking content: application/json: schema: type: object properties: uniqueId: type: string description: Unique ID of the booking example: 6199b5d4-093f-4b29-bf3c-1603498de5f9 capacityReservationId: type: string description: Capacity reservation ID for the booking. Use this when creating the booking to ensure reserved capacity is utilised example: c07128c8-adb1-45a0-9241-dc3875518468 costs: type: object properties: total: type: number description: Total booking cost including taxes and fees example: 96.95 totalIgnoringDeposit: type: number description: Total booking cost ignoring any deposit amount payable example: 96.95 totalExcludingFees: type: number description: Total booking cost excluding fees payable by the customer example: 1.95 amountOwing: type: number description: The amount currently owing on the booking example: 96.95 tax: type: number description: The tax amount included in the booking total example: 8.64 taxExclusive: type: number description: The value of items in the booking which have tax exclusive prices example: 0 transactionFee: type: number description: Value of transaction fees on the booking example: 1.95 cardFee: type: number description: Value of credit card fees on the booking example: 0 productFee: type: number description: Value of product fees on the booking example: 1.5 productFees: type: array description: The product fee rules charged on the booking items: type: object properties: productFeeId: type: integer description: Identifier of the product fee rule example: 42 name: type: string description: Name of the product fee example: Booking fee description: type: string description: Description of the product fee example: Applied to online bookings amount: type: number description: Fee amount charged on the booking example: 1.5 discount: type: number description: Value of discounts on the booking. Discounts are already factored in to the booking totals example: 5 discounts: type: array items: type: object properties: discount: type: number description: Amount discounted using this discount code example: 5 code: type: string description: Discount code used example: JMA99281 giftCards: type: array items: type: object properties: giftCardNumber: type: string description: Gift Card number being redeemed example: '8839920172' amountDeducted: type: number description: Dollar value being deducted from the gift card when this booking is published example: 20 paymentJwt: type: string description: JSON Web Token for taking payment example: eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJpbn '409': description: Invalid Booking content: application/json: schema: type: object properties: errors: type: array items: type: object properties: name: type: string description: Name of the error example: VenueCapacity message: type: string description: Error message example: Venue capacity will be exceeded requestBody: content: application/json: schema: type: object required: - externalId - customer - items properties: externalId: type: string description: 3rd party booking reference example: UJJSK28374 name: type: string description: Title of the booking. Name can be different to the booking owner name (defaults to the booking owner's name if not specified) example: Sports Group Booking comments: type: string description: Additional detail about the booking example: Customer has not visited before purchaseDate: type: string description: Optionally provide the creation datetime in UTC - generally used when re-creating bookings and needing to retain the original datetime example: '2020-07-29T06:57:18.5306035+00:00' capacityReservationId: type: string description: The GUID returned from the capacity reservation API - it's recommended to use the capacity reservation API otherwise the request may be rejected example: c07128c8-adb1-45a0-9241-dc3875518468 companyId: type: integer description: Id of the company making the booking example: 12345 customer: $ref: ../models/BookingCreateCustomer.yaml items: type: array items: $ref: ../models/BookingCreateItem.yaml discounts: type: array items: type: object properties: code: type: string description: Discount code being used on the booking (can apply multiple) example: AN829910 giftCards: type: array items: type: object properties: giftCardNumber: type: string description: Gift Card number being redeemed example: '8839920172' sendConfirmations: type: boolean description: When true ROLLER will send the booking confirmation / tickets to the customer automatically example: false customerPaysFees: type: boolean description: When true fees setup in ROLLER are applied. Please note if manual `creditCardFees` are provided in the request it will override all fees setup in ROLLER. metadata: type: object description: 'User-defined key-value pairs to store against the booking. Supports up to 20 entries. Keys are case-sensitive strings (max 40 characters). Values are strings (max 500 characters, HTML stripped on write).' additionalProperties: type: string example: reservationSource: partner-portal groupId: '881234' description: '' description: '> Create a draft booking with discounts and gift card payments, then receive back the associated booking cost information and a secure payment JSON Web Token to process payment' operationId: create-draft-booking tags: - Booking Management /bookings/draft/publish: post: summary: Publish draft booking (no payment) responses: '200': description: Publish Draft Booking content: application/json: schema: type: object properties: bookingReference: type: string description: Booking ID of the published booking example: '52776970' uniqueId: type: string description: uniqueId of the publised booking' example: c07128c8-adb1-45a0-9241-dc3875518468 '409': description: Invalid Booking content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string description: Error message example: Draft not found requestBody: content: application/json: schema: type: object required: - uniqueId properties: uniqueId: type: string description: Unique ID of the booking to be published (provided in the Create Draft Booking response) example: afb0feb2-383d-415c-bcbe-9e1644ec2598 description: '> Publish a draft booking that does not require any payment. Only bookings which have an owing amount of 0.0 can be published this way.' operationId: publish-draft-booking-no-payment tags: - Booking Management '/companies/{companyId}': get: summary: Get company detail description: Returns the profile of a venue company, including its primary contact and postal address. tags: - Company responses: '200': description: OK content: application/json: schema: $ref: ../models/Company.yaml '404': description: Not Found - Company does not exist operationId: get-company-detail put: summary: Update company detail description: 'Updates the profile fields of a venue company. Contact details are managed via guest endpoints. Omitted or `null` optional fields preserve their existing values.' tags: - Company requestBody: content: application/json: schema: $ref: ../models/CompanyUpdate.yaml responses: '200': description: OK content: application/json: schema: $ref: ../models/Company.yaml '404': description: Not Found - Company does not exist operationId: update-company-detail parameters: - $ref: '#/components/parameters/companyId' /discounts: post: summary: Create discount description: Creates a new discount requestBody: content: application/json: schema: $ref: ../models/DiscountCreate.yaml responses: '200': description: Successful response content: application/json: schema: type: object properties: discountId: type: integer example: 266 description: Unique ID of a discount configuration operationId: create-discount tags: - Discount '/discounts/{discountId}': get: summary: Get discount description: Gets a discount configuration for a given known discount ID responses: '200': description: Successful response content: application/json: schema: $ref: ../models/Discount.yaml operationId: get-discount tags: - Discount put: summary: Update discount description: Updates a discount configuration for a given known discount ID requestBody: content: application/json: schema: $ref: ../models/DiscountUpdate.yaml responses: '200': description: Successful response operationId: update-discount tags: - Discount parameters: - $ref: '#/components/parameters/discountId' '/discounts/{discountId}/codes': post: summary: Create discount codes description: Creates a new discount code for an existing discount configuration requestBody: content: application/json: schema: type: object required: - codes properties: codes: type: array description: "List of codes to add to the discount. \r\n\r\nCodes cannot be: \r\n- Only whitespace\r\n- Be longer than `32` characters\r\n- Already exist for any discount" maxItems: 1000 items: type: string maxLength: 32 responses: '200': description: Successful response operationId: create-discount-codes tags: - Discount delete: summary: Delete discount codes description: Deletes a discount code for an existing discount configuration responses: '200': description: Successful response requestBody: content: application/json: schema: type: object required: - codes properties: codes: type: array description: List of codes to delete from the discount. items: type: string operationId: delete-discount-codes tags: - Discount parameters: - $ref: '#/components/parameters/discountId' /discounts/validate: post: summary: Validate discount codes responses: '200': description: Discount validation content: application/json: schema: type: object properties: discounts: description: Discounts applied type: array items: type: object properties: discount: type: number description: Amount discounted example: 22.5 code: type: string description: Discount code used example: '123456789' validationMessage: type: string description: Reason discount was not applied (only present if discount not valid) example: Discount is not valid for this transaction items: type: array description: Items validated against the discount items: type: object properties: itemNumber: type: string description: 'Identifier for this item in the booking. Can be provided in validation request, if not, ROLLER will return a unique ID' example: 0a2c56ea-80a3-4abc-aef9-47a0b90f9503 discount: type: number description: Amount discounted on this item example: 22.5 bookingCosts: type: object properties: total: type: number description: 'Total value of the booking including tax, and factoring in discounts' example: 27.5 totalIgnoringDeposit: type: number description: Total value of the booking excluding any deposit amount owing example: 27.5 totalExcludingFees: type: number description: Total value of the booking excluding any booking fees example: 26 amountOwing: type: number description: Amount currently owing on the booking total example: 27.5 tax: type: number description: Total tax amount on the booking total example: 2.75 taxExclusive: type: number description: Amount of tax that is on top of the product price (included in total tax number) example: 0 transactionFee: type: number description: Amount of transaction fees on the booking example: 0 cardFee: type: number description: Amount of credit card fees on the booking example: 0 productFee: type: number description: Amount of product fees on the booking example: 1.5 productFees: type: array description: The product fee rules charged on the booking items: type: object properties: productFeeId: type: integer description: Identifier of the product fee rule example: 42 name: type: string description: Name of the product fee example: Booking fee description: type: string description: Description of the product fee example: Applied to online bookings amount: type: number description: Fee amount charged on the booking example: 1.5 discount: type: number description: Amount of discount on the booking example: 22.5 requestBody: content: application/json: schema: type: object properties: items: type: array items: type: object properties: productId: type: string description: Product ID of an item in the booking quantity: type: integer description: Quantity of that product in the booking bookingDate: type: string description: Date that the booking is for (NOT the date the booking is being made) priceOverride: type: number description: 'Price per quantity of the item (if left blank, uses default price)' discounts: type: array items: type: object properties: code: type: string description: The discount code being applied (you can use multiple) description: |- > #### This endpoint is being deprecated > Please use the [**booking costs endpoint**](#/paths/~1bookings~1draft~1costs/post) to validate discounts instead. > Validate whether a discount code is valid and the value of that discount against products in ROLLER. > You can send a request with multiple products, quantities and discount codes, and you will receive the specific discounted amounts against each item, as well as the booking totals operationId: validate-discount-codes deprecated: true tags: - Discount '/bookings/{uniqueId}': put: summary: Update a booking responses: '200': description: Success '409': description: Invalid Booking content: application/json: schema: type: object properties: errors: type: array items: type: object properties: name: type: string description: Name of the error example: VenueCapacity message: type: string description: Error message example: Venue capacity will be exceeded requestBody: content: application/json: schema: type: object properties: name: type: string description: Title of the booking. Name can be different to the booking owner name (defaults to the booking owner's name if not specified) example: Sports Group Booking maxLength: 128 comments: type: string description: Additional detail about the booking example: Customer has not visited before maxLength: 500 metadata: type: object description: 'User-defined key-value pairs to update on the booking. Uses merge semantics — keys present in this object are set or updated, keys absent from the object are left unchanged. Set a key''s value to `null` to remove it. Supports up to 20 entries. Keys are case-sensitive strings (max 40 characters). Values are strings (max 500 characters, HTML stripped on write).' additionalProperties: type: - string - 'null' example: reservationSource: partner-portal groupId: null newItems: type: array items: type: object properties: productId: type: integer description: Variation ID (Child Product ID) of the product being added example: 12345679 quantity: type: integer description: The number of products / items being purchased. The number of tickets generated is Quantity * Product.GroupSize example: 5 bookingDate: type: string description: The date when the product / event is occurring - depending on the product configuration this may just be the date of the booking where the booking is valid until X time in the future. ISO8601 date format only e.g. 2020-03-21 example: '2020-07-29' startTime: type: string description: 'Session start time in 24h format e.g. 00:00 = Midnight, 23:59 = 11:59 PM' example: '14:00' priceOverride: type: number description: Use this when the price you're charging is not the same as the product price in ROLLER example: 23.8 partyPackageInclusions: type: array description: 'Define which Party Package inclusions have been selected by the guest. Applies to products configured with legacy inclusions - use `optionSetSelections` instead where the product is configured with option sets.' items: type: object properties: productId: type: string description: Variation ID (Child Product ID) of the product selected as an inclusion example: '9817726' quantity: type: integer description: The quantity of the selected inclusion example: 2 optionSetSelections: type: array description: "Define which option set selections have been made for a package or party package product. Use this in place of `partyPackageInclusions` where the product is configured with option sets.\r\n\r\n- Only the selections you supply are created - an option set is not auto-filled to its required quantity.\r\n- This requires ROLLER first enables a meta setting for your platform to use." items: type: object properties: productPackageOptionSetId: type: integer description: The ID of the option set the selection applies to. Returned as `packageOptionSets[].productPackageOptionSetId` by [**Get product detail**](https://docs.roller.app/docs/api/rest/operations/get-product-detail). example: 4471 productId: type: integer description: Variation ID (Child Product ID) of the option chosen from the option set example: 9817726 quantity: type: integer description: The number of this option to include - one inclusion item is created per unit of quantity example: 2 tickets: type: array description: Optionally provide ticket details - the number of tickets must match Quantity * Product.GroupSize items: type: object properties: id: type: string description: Custom ticket ID. When not supplied the default is `-` example: 277AHU7610 name: type: string description: The name of the ticket holder example: John Smith idsToRemove: type: array description: The `bookingItemId`'s of the items to remove from the booking items: type: integer example: 23423882 itemsToUpdate: type: array description: List of booking items that can have additional fields updated items: type: object required: - bookingItemId properties: bookingItemId: type: string description: The `bookingItemId` of the booking item within the booking to update. This is not the `ticketId`. example: '2837466571' bookingEndDate: type: - string - 'null' description: 'The new date for when the booking item is to expire, in the format: `yyyy-MM-dd`' example: '2025-07-14' tickets: type: array description: List of tickets that can have additional fields updated items: type: object properties: ticketId: type: string description: The ID of the ticket within the booking item to update data for. example: 92837746-42383746 customTicketId: type: string description: "The new custom ticket ID for the ticket.\r\n\r\n- Note this will override any existing `customTicketId`.\r\n- Provide an empty string to remove any existing `customTicketId`.\r\n- Validation to prevent duplicate `customTicketId`'s is only available when creating bookings (Duplicates are allowed when updating)." example: wristband_0122 maxLength: 32 name: type: string description: "The name of the ticket holder.\r\n\r\n- Provide an empty string to remove the existing `name`.\r\n- `NULL`values are ignored; no changes will be made to the existing name." example: John Smith maxLength: 50 discounts: type: object description: Discounts to add to or remove from the booking. The booking cost is recalculated to reflect the change. When omitted, the booking's discounts are unchanged properties: add: type: array description: "The discount codes or custom discounts to add to the booking.\r\n\r\n- Every code is validated before any change is applied - if any code is invalid the whole request is rejected and no discounts are added or removed.\r\n- Unlike [**Create a booking**](https://docs.roller.app/docs/api/rest/operations/create-a-booking), restricting a custom discount to specific products via `productIds` is not supported when updating." items: type: object properties: code: type: string description: The discount code used by the customer example: JMA99281 amount: type: number description: The dollar amount of a custom discount that applies to the booking as a whole example: 4.5 percentage: type: number description: "The percentage of a custom discount that applies to the booking as a whole, eg. 10 for 10% off" example: 10 removeByDiscountId: type: array description: "The IDs of the discounts to remove from the booking, matching the `discountId` returned on the booking's applied discounts (see [**Get booking detail**](https://docs.roller.app/docs/api/rest/operations/get-booking-detail) with `includeDiscounts=true`). If any supplied ID is not applied to the booking the request is rejected." items: type: integer example: 4471 description: '' description: '> Update booking details, add/remove items, or add/remove discount codes from a booking.' operationId: update-a-booking tags: - Booking Management delete: summary: Delete a booking responses: '200': description: Deleted successfully description: "Delete a booking, along with all associated transaction records.\r\n\r\n> * You can only delete bookings you've made via the API\r\n> * You can only delete future bookings\r\n> * Cancelled bookings cannot be deleted\r\n> * All records of the booking will be deleted from all ROLLER reports" operationId: delete-a-booking tags: - Booking Management requestBody: content: application/json: schema: type: object properties: comments: type: string description: Optionally provide a reason for deleting the booking get: summary: Get booking detail description: "Returns detail of a specific booking based on the booking.\r\n\r\n> `bookingReference` (i.e. the ROLLER `bookingId`) can be used instead of `uniqueId` as the path parameter." parameters: - name: includeDiscounts in: query required: false schema: type: boolean default: false description: When `true`, the response includes the `discounts` array listing the discount codes applied to the booking responses: '200': description: Successful content: application/json: schema: $ref: ../models/BookingDetail.yaml '404': description: Booking not found operationId: get-booking-detail tags: - Booking Information parameters: - $ref: '#/components/parameters/uniqueId' '/bookings/{uniqueId}/cancel': post: summary: Cancel a booking responses: '200': description: Success '403': description: Forbidden content: application/json: schema: type: string example: You can only cancel bookings you've made via the API requestBody: content: application/json: schema: type: object required: - issueRefund properties: issueRefund: type: boolean description: Determines if any booking payments are refunded default: true refundType: description: The method of payment refund (Required when `issueRefund` is `true`) enum: - CreditCard - Cash - Eftpos - Cheque - BankTransfer - GiftCard - Other refundTransactionId: type: string description: Optional transaction ID of the refund (Only relevant when `issueRefund` is `true`) example: UUDJS882993 maxLength: 32 refundTransactionDate: type: - string - 'null' description: Optional datetime in UTC of the refund transaction (Only relevant when `issueRefund` is `true`) example: '2020-07-30T09:03:06.4749865+00:00' comments: type: string description: Optional comments to add against the refund in booking activity (Only relevant when `issueRefund` is `true`) example: Customer called and cancelled their booking. description: '' description: | Cancel a booking, and optionally mark it as refunded in a single transaction. > * Only bookings created via API can be cancelled via API > * You can only cancel future bookings > * Cancelled bookings will still be visible in some pages in VM > * Any associated payment records will still be present for cancelled bookings > * Refunds must be processed externally of ROLLER - Only a record of the refund can be added via API. operationId: cancel-a-booking tags: - Booking Management parameters: - $ref: '#/components/parameters/uniqueId' '/bookings/{uniqueId}/payments': post: summary: Add transaction record description: | * Add a transaction record (Such as a **payment** or **refund**) to an existing booking in ROLLER. * Payments must be processed externally of ROLLER, only a record of a successful transaction can be created via the API. > #### Gift card payments > * To pay with a gift card, set `paymentType` to `Giftcard` and provide the `giftcardNumber`. Only ROLLER-issued gift cards are supported. > * To refund to a gift card, use a negative `amount` with `paymentType` `Giftcard` — the refund is returned to the same card. > #### When processing refunds > * Ensure you do not refund more than the amount already paid on the booking > * This only affects the record in ROLLER and does not actually refund the guest. The refund must still be actioned separately (for example refunded via your payment gateway). responses: '200': description: Booking detail content: application/json: schema: type: object properties: uniqueId: type: string description: Unique Payment ID example: ffdae420-a912-4d93-9234-9faca5e6194f '409': description: Conflict content: application/json: schema: type: object properties: errors: type: array items: type: object properties: name: type: string description: Name of the error example: Booking message: type: string description: Error message example: Booking 'ffdae420-a912-4d93-9234-9faca5e6194f' not found requestBody: content: application/json: schema: type: object required: - id - paymentType - amount properties: id: type: string description: Unique payment or transaction ID. This must be unique otherwise the payment record will not be added. example: HYA728830013 paymentType: type: string enum: - CreditCard - CreditCardPreAuth - Cash - Cheque - BankTransfer - Other - Giftcard description: The tender type used example: CreditCard amount: type: number description: "The payment total including fees, in venue local currency. Use a negative amount for refunds. \r\n" example: 25.5 creditCardFees: type: number description: Credit card fees associated with the payment example: 1.5 transactionDate: type: string description: Optionally provide the transaction datetime in UTC - generally used when re-creating bookings and needing to retain the original datetime example: '2020-07-29T06:57:18.5326035+00:00' giftcardNumber: type: string maxLength: 64 description: 'The gift card number to charge or refund. Required when `paymentType` is `Giftcard`, and ignored for all other payment types. Only ROLLER-issued gift cards are supported.' example: '2606947188' operationId: add-transaction-record tags: - Transaction parameters: - $ref: '#/components/parameters/uniqueId' '/bookings/{uniqueId}/payments/tips': post: summary: Add a tip description: | Add a tip to an existing booking as a tip-only payment. The tip is assigned to the general tip pool. * The tip `amount` must be a positive value — zero and negative amounts are rejected. * `Giftcard` is not a supported `paymentType` for tips. * Refunding a tip is not supported via the API; reconcile tips in Venue Manager or POS. responses: '201': description: Tip recorded content: application/json: schema: type: object properties: uniqueId: type: string description: Unique payment ID for the recorded tip example: ffdae420-a912-4d93-9234-9faca5e6194f '400': description: 'Bad request - the amount was zero or negative, or Giftcard was used as the payment type.' '409': description: Conflict content: application/json: schema: type: object properties: errors: type: array items: type: object properties: name: type: string description: Name of the error example: Booking message: type: string description: Error message example: Booking 'ffdae420-a912-4d93-9234-9faca5e6194f' not found requestBody: content: application/json: schema: type: object required: - id - paymentType - amount properties: id: type: string maxLength: 32 description: Unique payment or transaction ID. This must be unique otherwise the tip record will not be added. example: HYA728830013 paymentType: type: string enum: - CreditCard - CreditCardPreAuth - Cash - Cheque - BankTransfer - Other description: The tender type used to fund the tip. `Giftcard` is not supported. example: CreditCard amount: type: number description: The tip amount in the venue's local currency. Must be a positive value. example: 5 tipNote: type: string maxLength: 1000 description: Optional note attached to the tip. example: Great service operationId: add-a-tip tags: - Transaction parameters: - $ref: '#/components/parameters/uniqueId' '/bookings/{uniqueId}/payments/links': post: summary: Create payment link description: "Create a payment link to send to a recipient email or phone (via SMS) to take payment.\r\n\r\nTo see delivery status of the payment link, please see the activity log on the relevant booking in VM.\r\n\r\n* Payment links **can** be generated for bookings created via both API, and via ROLLER applications.\r\n* Payment links **cannot** be created for API-draft, or venue-draft bookings.\r\n\r\nNote: If both `email` and `phone` is provided, `email` will be ignored and an SMS will be sent.\r\nNote: Sending payment links to a recipient `phone` (via SMS) is unsupported in **Playground**. \r\n\r\n> This will not create a guest record of the recipient, or attach them to the booking in VM.\r\n" responses: '200': description: Success content: application/json: schema: type: object properties: id: type: string description: Payment link ID example: '2566' url: type: string description: Payment link URL example: 'https://...' '400': description: 'Bad Request - Validation issue (eg: Email or phone is required).' '404': description: Not Found - No booking found for `uniqueIdentifier` '409': description: 'Conflict - Business rule (eg: Booking already paid, or payment link requests more than current owing amount).' requestBody: content: application/json: schema: type: object required: - amount - email - phone properties: amount: type: number description: Amount payable via the payment link example: 32.2 email: type: string description: Recipient email (Not required if `phone` is provided) example: finn.mertons@roller.com phone: type: string description: Recipient phone (Not required if `email` is provided) example: '0497911898' operationId: create-payment-link tags: - Transaction x-internal: true parameters: - $ref: '#/components/parameters/uniqueId' '/bookings/{uniqueId}/payments/links/{paymentLinkId}': parameters: - $ref: '#/components/parameters/uniqueId' - $ref: '#/components/parameters/paymentLinkId' delete: summary: Cancel payment link tags: - Transaction responses: '200': description: OK '404': description: Not Found - No booking/payment link found for `uniqueIdentifier`/`paymentLinkId` '409': description: 'Conflict - "Payment link `{`paymentLinkId`}` does not belong to booking `uniqueIdentifier`' operationId: cancel-payment-link description: 'Cancel a payment link so it can no longer be used to take payment against the booking. ' x-internal: true '/bookings/{uniqueId}/form-responses': parameters: - $ref: '#/components/parameters/uniqueId' get: summary: Get booking form responses description: 'Returns all form responses captured against a booking, structured as questions and answers. A booking may have more than one form response where multiple forms were completed.' operationId: get-booking-form-responses tags: - Booking Information responses: '200': description: Successful content: application/json: schema: $ref: ../models/BookingFormResponses.yaml examples: Example 1: value: formResponses: - formName: Waiver and safety form responses: - question: What is your t-shirt size? answer: Medium - groupName: Emergency contact items: - question: Contact name answer: Jane Smith - question: Contact phone answer: '0400000000' '404': description: Booking not found '/customers/{customerId}': get: summary: Get customer detail responses: '200': description: Successful content: application/json: schema: $ref: ../models/CustomerDetail.yaml '404': description: Not Found - Customer does not exist description: "\r\n\r\n> #### This endpoint is being deprecated\r\n> `Customer` as a name/object has been renamed to `Guest`.\r\n> \r\n> Please use the [**get guest detail endpoint**](#/paths/~1guests~1{guestId}/get) to retrieve customer detail instead.\r\n\r\n\r\nThis endpoint returns details of a customer." operationId: get-customer-detail deprecated: true tags: - Guest parameters: - $ref: '#/components/parameters/customerId' '/customers/{customerId}/multi-passes': get: summary: Get guest multi-passes responses: '200': description: Successful content: application/json: schema: type: array items: $ref: ../models/CustomerMultiPass.yaml '404': description: Not Found - Guest does not exist description: Get a list of guest multi-pass balances including expiry and exhaustion status. operationId: get-guest-multi-passes tags: - Guest parameters: - $ref: '#/components/parameters/customerId' '/guests/{guestId}': get: summary: Get guest detail tags: - Guest responses: '200': description: OK content: application/json: schema: $ref: ../models/Guest.yaml '404': description: Not Found - Guest does not exist operationId: get-guest-detail description: Returns details of a guest. parameters: - $ref: '#/components/parameters/guestId' put: summary: Update guest detail tags: - Guest responses: '200': description: OK operationId: update-guest-detail requestBody: content: application/json: schema: $ref: ../models/Guest.yaml description: Enables updating the details of a guest record. '/signed-waivers/{signedWaiverId}': parameters: - $ref: '#/components/parameters/signedWaiverId' get: summary: Get signed waiver tags: - Guest responses: '200': description: OK content: application/json: schema: $ref: ../models/SignedWaiver.yaml examples: Example 1: value: signedWaiverId: 18829121 waiverId: 13 firstName: Steven lastName: Toast guestId: 64310293 dateOfBirth: '1993-07-14' email: steven@toastoflondon.com contactNumber: '0475755223' isForMinor: false expiryDate: '2026-07-14T03:43:40.4085882Z' isValid: true createdDate: '2020-07-31T03:43:40.4085882Z' operationId: get-signed-waiver description: Retrieve a waiver signed by a guest '/signed-waivers/{signedWaiverId}/form-responses': parameters: - $ref: '#/components/parameters/signedWaiverId' get: summary: Get signed waiver form responses description: 'Returns the form responses captured on a signed waiver, structured as questions and answers. Returns an empty object when the waiver has no associated form response.' operationId: get-signed-waiver-form-responses tags: - Guest responses: '200': description: OK content: application/json: schema: $ref: ../models/SignedWaiverFormResponses.yaml examples: Example 1: value: responses: - question: What is your t-shirt size? answer: Medium - groupName: Emergency contact items: - question: Contact name answer: Jane Smith - question: Contact phone answer: '0400000000' '404': description: Signed waiver not found /redemptions: post: tags: - Redemption summary: Redeem tickets responses: '200': description: Redeemed successfully '409': description: "Invalid redemption. \r\n\r\nPossible error messages:\r\n* Ticket does not exist\r\n* Booking Cancelled\r\n* Ticket is not valid for this date\r\n* Ticket IDs must be unique per request\r\n* Ticket usage exhausted\r\n* Product type not accepted\r\n* Membership Invalid\r\n* Ticket redemption usage exhausted\r\n* Redemption device not found\r\n* Duplicate custom ticket IDs found\r\n* Custom ticket ID not found\r\n\r\nIf using **Redemption device** setting `Validate session times`:\r\n* Ticket cannot be redeemed before the session start time\r\n* Ticket cannot be redeemed after the session end time\r\n" content: application/json: schema: type: object properties: errors: type: array items: type: object properties: name: type: string description: Name of the error example: InvalidRedemption message: type: string description: Error message example: Ticket usage exhausted ticketId: type: string description: TicketId with the error example: 2883977-98736472 requestBody: content: application/json: schema: type: object properties: tickets: type: array maxItems: 10 uniqueItems: true items: type: object required: - ticketId properties: ticketId: type: string description: ROLLER Ticket ID being redeemed. This can either be the ROLLER generated `ticketId` or a `customTicketId` if applied. example: 3288921-29937813 redemptionDate: type: string description: 'Optionally provide the redemption datetime in UTC. If not present, the datetime of the API call will be used' example: '2020-07-29T06:57:18.5326035+00:00' redemptionDevice: type: string description: 'The name of the device where the ticket is being redeemed. Includes redemption devices, POS, MCI and SSK devices.' description: "> Redeem tickets in ROLLER\r\n\r\n* There is a maximum of 10 ticket redemptions per call\r\n* Redeemed Ticket IDs must be unique per call\r\n* Only the following products are supported for redemption via API:\r\n * Standard Passes\r\n * Session Passes\r\n * Recurring Sessions\r\n * Memberships (the booking item, not the membership discount) " operationId: redeem-tickets /giftcards: post: tags: - Gift Card summary: Create gift cards operationId: create-gift-cards description: "Create one or more gift cards for a single gift card product. Each entry in `giftCards` creates one card, and all cards are created against a single booking owned by `bookingOwner`.\r\n\r\nGift card numbers are returned in `giftCardNumbers`, in the same order as the request — a caller-supplied `giftCardNumber` is echoed back, otherwise a generated number is returned. Cards are activated asynchronously shortly after creation.\r\n\r\n* `externalId` is unique per venue and acts as an idempotency key. Reusing one returns a `409`.\r\n* `value` is required for open-value gift card products, and rejected for fixed-value products.\r\n* A `recipient` must include both `name` and `email`, or neither.\r\n* When `sendGiftCardEmails` is `true`, every card must have a recipient `name` and `email`.\r\n* `deliveryDateTime` must be in the future (UTC)." requestBody: content: application/json: schema: type: object required: - externalId - productId - bookingOwner - giftCards properties: externalId: type: string maxLength: 64 description: 'External reference for this request. Unique per venue, and acts as an idempotency key.' example: RESELLER-ORDER-2026-0045 productId: type: integer format: int32 description: The ID of the gift card product to create cards from. Must be a gift card product in the venue. example: 9573 bookingOwner: type: object description: The primary contact for the booking the gift cards are created against. required: - firstName - lastName - email - phone properties: firstName: type: string maxLength: 32 example: Jordan lastName: type: string maxLength: 32 example: Avery email: type: string maxLength: 256 description: Receives the booking confirmation when `sendConfirmations` is `true`. example: jordan.avery@acme-resellers.com phone: type: string maxLength: 20 example: +61 400 123 456 giftCards: type: array minItems: 1 description: The gift cards to create. Each entry produces one card. items: type: object properties: giftCardNumber: type: string minLength: 6 maxLength: 128 description: Optional custom gift card number. Must be unique within the request and the venue. Omit to have a number generated. example: ACME-PROMO-000124 value: type: number description: 'The value to load on the card. Required for open-value products, rejected for fixed-value products. Must be greater than zero.' example: 50 recipient: type: - object - 'null' description: The recipient the card is addressed to. Omit or set to null for an unassigned card. properties: name: type: string description: Required together with `email`. example: Sam Rivera email: type: string description: Required together with `name`. example: sam.rivera@example.com message: type: string maxLength: 500 description: Optional personal message shown on the card and in the recipient email. example: Happy birthday! Enjoy a day out on us. deliveryDateTime: type: string format: date-time description: 'Optional scheduled send time in UTC. Must be in the future, and requires a recipient `name` and `email`.' example: '2026-12-24T09:00:00Z' sendConfirmations: type: boolean default: false description: 'When `true`, sends the booking confirmation to the booking owner after creation.' sendGiftCardEmails: type: boolean default: false description: 'When `true`, sends each card''s recipient their gift card email. Every card must then have a recipient `name` and `email`.' responses: '200': description: Gift cards created content: application/json: schema: type: object properties: giftCardNumbers: type: array description: 'The created gift card numbers, in the same order as the gift cards in the request. Caller-supplied numbers are echoed back; otherwise the generated number is returned.' items: type: string example: - '2606947188' - '2606749291' - ACME-PROMO-000124 '400': description: 'Bad Request - The request body failed validation (eg: a required field is missing, an email is invalid, or a length limit is exceeded).' '409': description: 'Conflict - A business rule was violated (eg: the externalId already exists, the product is not a gift card, or a gift card number is not unique).' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: name: type: string description: Name of the error example: ExternalId message: type: string description: Error message example: The booking RESELLER-ORDER-2026-0045 already exists /giftcards/balance: post: tags: - Gift Card summary: Get gift card balance operationId: get-gift-card-balance description: "Get the current balance and details of a gift card by its number.\r\n\r\nThe gift card number is sent in the request body because gift card numbers may contain characters that are unsafe in a URL." requestBody: content: application/json: schema: type: object required: - giftCardNumber properties: giftCardNumber: type: string description: The gift card code (unique identifier). example: '2606947188' responses: '200': description: Gift card balance content: application/json: schema: type: object properties: giftCardNumber: type: string description: The gift card code (unique identifier). example: '2606947188' balance: type: - number - 'null' description: The current balance of the gift card. example: 35.5 initialValue: type: - number - 'null' description: 'The initial value of the gift card when it was issued. May be null, as this is not always available for external gift cards.' example: 50 expiryDate: type: - string - 'null' format: date-time description: 'The date the gift card expires. If null, the gift card does not expire.' example: '2027-12-24T00:00:00' '409': description: 'Conflict - The gift card could not be found, or the request was invalid (eg: gift card number is required).' content: application/json: schema: type: object properties: errors: type: array items: type: object properties: name: type: string description: Name of the error example: GiftCardNumber message: type: string description: Error message example: Gift card number is required /webhooks: post: tags: - Webhooks summary: Create webhook responses: '201': description: Webhook created content: application/json: schema: type: object properties: webhookId: type: integer format: int32 description: Unique ID of the webhook example: 233 createdDate: type: string description: Date the webhook was created example: '2022-02-03T02:50:01.2354035Z' configuration: $ref: ../models/WebhookConfiguration.yaml requestBody: content: application/json: schema: $ref: ../models/CreateWebhookConfiguration.yaml examples: {} description: "Create a webhook.\r\n\r\nFor more information see [**Webhooks Overview**](https://docs.roller.app/docs/api/webhooks-overview).\r\n\r\n>Note:\r\n> - `enabled` must be set to `true` to make the webhook active\r\n> - The `events` object is only required for at least **one** webhook type. " operationId: create-webhook get: tags: - Webhooks summary: Get webhooks responses: '200': description: Webhook endpoints content: application/json: schema: type: object properties: webhookId: type: integer format: int32 description: Unique ID of the webhook createdDate: type: string example: '2022-02-03T02:50:01.2354035Z' description: Date the webhook was created configuration: $ref: ../models/WebhookConfiguration.yaml description: "Get information about existing webhooks.\r\n\r\nFor more information see [**Webhooks Overview**](https://docs.roller.app/docs/api/webhooks-overview)." operationId: get-webhooks '/webhooks/{webhookId}': put: summary: Update webhook tags: - Webhooks responses: '200': description: OK operationId: update-webhook description: "Updates an existing webhook.\r\n\r\nFor more information see [**Webhooks Overview**](https://docs.roller.app/docs/api/webhooks-overview)." requestBody: content: application/json: schema: $ref: ../models/CreateWebhookConfiguration.yaml examples: Example 1: value: url: 'https://your-url-to-receive-webhook.com/12345' enabled: true authentication: apiKey: CRM Trigger Webhook 002 webhooks: booking: events: - Created include: externalId: true tickets: true membershipDetail: true locations: true customerFlags: true metadata: true filter: channels: - VenueManager productTypes: - Pass productIds: - 42331 productCategory: Entry Tickets redemption: events: - Created include: membershipDetail: true filter: productIds: - 42331 productCategory: Entry Tickets customer: events: - Created include: flags: true delete: tags: - Webhooks summary: Delete webhook responses: '200': description: Webhook deleted description: "Delete an existing webhook.\r\n\r\nFor more information see [**Webhooks Overview**](https://docs.roller.app/docs/api/webhooks-overview)." operationId: delete-webhook parameters: - $ref: '#/components/parameters/webhookId' /venues/me: get: tags: - Venue Information summary: Get venue detail description: '> Returns detail of the venue for your API keys' responses: '200': description: Successful content: application/json: schema: type: object properties: id: type: integer description: ROLLER Venue ID example: 20981 name: type: string description: Venue name example: ROLLER World Australia timeZone: type: string description: Venue local timezone example: '(UTC+10:00) Brisbane' ianaTimeZone: type: string example: '(UTC+10:00) Brisbane' description: IANA timezone countryCode: type: string description: Country code where the venue is located example: AU country: type: string description: Country the venue is located example: Australia currency: type: string description: Venue trading currency example: AUD locale: type: string description: locale code where the venue is located example: en-AU productPricesIncludeTax: type: boolean description: Whether or not the prices of products for the venue include taxes example: true transactionFeePercent: type: number description: The % amount of fees charged to customers for Online Checkout payments example: 3 creditCardFeePercent: type: number description: The % amount of fees charged on Card payments on the Online Checkout and in Venue Manager example: 2.5 feePerTransaction: type: number description: The $ amount of fees charged to customers for Online Checkout payments example: 1.5 codeOfConduct: type: string description: The terms and conditions set by the venue for customers when they make a purchase example: customers must agree to xyz paymentSettings: type: object properties: apiUrl: type: string description: URL for the payment service example: 'https://payment.service.roller.app' configurationId: type: string example: ee1807ae-58f8-4438-b17b-b60f7810a0cf format: uuid integrationId: type: string example: bf8abcf0-f773-42cb-b1ea-f42b9f1d488b format: uuid taxes: type: array items: type: object properties: id: type: integer example: 45 description: Unique taxId name: type: string example: State Tax description: Name of the defined tax rate taxPercent: type: number example: 8.5 description: Percent of the defined tax rate (Expressed as a number between 0 - 100) isDefault: type: boolean description: Whether this tax rate is the default for all products (Until a different tax rate is chosen or a tax override is set on the product) taxComponents: type: array description: List of tax components applicable to the venue items: type: object properties: id: type: string name: type: string taxPercent: type: string venueGroups: type: array description: List of venue groups (i.e. tags) defined within HQ venues that group together controlled venues items: type: object properties: hqVenueGroupTag: type: string description: Name of the HQ venue tag hqVenueUniqueIds: type: array description: List of controlled venue IDs that belong to this HQ venue tag items: type: string format: uuid operationId: get-venue-detail /netsuite-settings: get: summary: Get NetSuite Settings tags: - Venue Information responses: '200': description: OK content: application/json: schema: $ref: ../models/NetSuiteSettings.yaml operationId: get-netsuite-settings x-stoplight: id: 2s4y3w6nppfgh description: Retrieve the NetSuite configuration fields available for this venue. put: summary: Update NetSuite Settings tags: - Venue Information responses: '200': description: OK operationId: update-netsuite-settings x-stoplight: id: nz5lwfjddm03o requestBody: content: application/json: schema: $ref: ../models/NetSuiteSettings.yaml description: Update the NetSuite configuration fields available for this venue. /staff: post: summary: Create staff tags: - Staff responses: '201': description: Created content: application/json: schema: $ref: ../models/StaffResponse.yaml '403': description: Forbidden - Staff management API may be disabled for the venue '409': description: Conflict - Validation or business rule error operationId: create-staff x-stoplight: id: h7d52xvbkchk1 description: 'Create a staff account. See [**managing staff via API**](https://docs.roller.app/docs/api/managing-staff) for more detail on staff account states and lifecycle.' requestBody: content: application/json: schema: $ref: ../models/StaffRequest.yaml '/staff/{uniqueId}': parameters: - schema: type: string format: uuid name: uniqueId in: path required: true description: Unique ID of the staff member get: summary: Get staff tags: - Staff responses: '200': description: OK content: application/json: schema: $ref: ../models/StaffResponse.yaml '403': description: Forbidden - Staff management API may be disabled for the venue '404': description: Not Found - Staff `uniqueId` not found operationId: get-staff x-stoplight: id: 8fxeddhz12zj8 description: Get staff detail put: summary: Update staff tags: - Staff responses: '200': description: OK content: application/json: schema: $ref: ../models/StaffResponse.yaml '403': description: Forbidden - Staff management API may be disabled for the venue '404': description: Not Found - Staff `uniqueId` not found '409': description: Conflict - Validation or business rule error operationId: update-staff x-stoplight: id: w4wkae8oqzmtt description: Update staff requestBody: content: application/json: schema: $ref: ../models/StaffRequest.yaml delete: summary: Delete staff tags: - Staff responses: '200': description: OK '403': description: Forbidden - Staff management API may be disabled for the venue '404': description: Not Found - Staff `uniqueId` not found operationId: delete-staff x-stoplight: id: n3q42kie5rjhu description: Delete staff '/staff/{uniqueId}/send-invitation': parameters: - schema: type: string format: uuid name: uniqueId in: path required: true description: Unique ID of the staff member post: summary: Send invitation tags: - Staff responses: '200': description: OK '403': description: Forbidden - Staff management API may be disabled for the venue '404': description: Not Found - Staff `uniqueId` not found '409': description: Conflict - Validation or business rule error operationId: send-invitation x-stoplight: id: r3ugbd9cpa2ev description: Send an email invitation to a staff member '/staff/{uniqueId}/lock': parameters: - schema: type: string format: uuid name: uniqueId in: path required: true description: Unique ID of the staff member post: summary: Lock staff tags: - Staff responses: '200': description: OK '403': description: Forbidden - Staff management API may be disabled for the venue '404': description: Not Found - Staff `uniqueId` not found '409': description: Conflict - Validation or business rule error operationId: lock-staff x-stoplight: id: xgit2fqsadj2f description: Lock a staff account. Prevents login via email/password and POS PIN. '/staff/{uniqueId}/unlock': parameters: - schema: type: string format: uuid name: uniqueId in: path required: true description: Unique ID of the staff member post: summary: Unlock staff tags: - Staff responses: '200': description: OK '403': description: Forbidden - Staff management API may be disabled for the venue '404': description: Not Found - Staff `uniqueId` not found '409': description: Conflict - Validation or business rule error operationId: unlock-staff x-stoplight: id: begjp2uz3c98u description: Unlock a staff account. Only possible if the staff member's email is verified. /segments: get: tags: - Segments summary: Get segments description: Returns the guest segments configured for the venue. responses: '200': description: Successful content: application/json: schema: type: array items: type: object properties: segmentId: type: integer description: Unique identifier of the segment example: 42 name: type: string description: Name of the segment example: VIP Members examples: Example: value: - segmentId: 42 name: VIP Members operationId: get-segments components: securitySchemes: OAuth2: type: oauth2 description: 'See [**authentication**](https://docs.roller.app/docs/api/authentication).' flows: clientCredentials: tokenUrl: 'https://api.roller.app/token' refreshUrl: '' scopes: {} parameters: uniqueId: name: uniqueId in: path schema: type: string example: 3c3aa180-bf44-4f0c-92a2-0cd120596014 description: Unique ID of a booking required: true blockId: name: blockId in: path required: true schema: type: integer example: 5156 description: The unique resource capacity block ID customerId: name: customerId in: path required: true schema: type: string example: '32444' description: ID of a guest record (Deprecated) (Same as `guestId`) deprecated: true guestId: name: guestId in: path required: true schema: type: string example: '32444' description: 'ID of a guest record (Formerly `customerId`, which is equivalent) ' webhookId: name: webhookId in: path required: true schema: type: string example: '17' description: ID of a registered webhook companyId: name: companyId in: path required: true schema: type: integer example: 4821 description: The venue-scoped company identifier discountId: name: discountId in: path required: true schema: type: integer example: 266 description: Unique ID of a discount configuration groupId: name: groupId in: path required: true schema: type: integer example: 214 description: Unique ID of a modifier group parentProductId: name: parentProductId in: path required: true schema: type: string example: '153444' description: 'Unique `productId` of the parent product ' signedWaiverId: name: signedWaiverId in: path required: true schema: type: string example: '18829122' description: Unique ID of the signed waiver record paymentLinkId: name: paymentLinkId in: path required: true schema: type: string description: Unique ID of a payment link generated to take payment against a booking security: - OAuth2: []