Reseller API Best Practice

Welcome to the Redeam Reseller API Best Practices page. This guide provides key recommendations for integrating with the Redeam Reseller API.

Broad API Field Implementation - the more the better

Implement the maximum number of fields and endpoints instead of the minimum to reduce future development work and support multiple suppliers with different requirements.

Redeam Suppliers might use all the functionalities and fields available in our APIs or just part of them, it depends on their requirements and product needs. To avoid future issues and delays we recommend you to implement as much as possible when developing to our Reseller API, so instead of focusing on the pilot partner use case only, take a broader approach, anticipating that for a second or third Supplier connection you might need to have additional fields implemented to make sure you get the data needed.

Future-Proof Your Integration: By mapping additional API fields now, you’ll reduce future onboarding work when connecting with new suppliers.

Optimize for Multiple Connections: Implement fields not only for the pilot partner but in anticipation of broader supplier needs.

Example: Map all available fields in the initial integration phase, anticipating different data requirements for future suppliers.

API Endpoints

Below is a list of required endpoints for a successful integration. Each endpoint has specific use cases for caching, retrieving detailed data, and supporting specific booking functionalities.

Retrieve Suppliers

GET/suppliers: Use this endpoint to temporarily store data in your system's cache, enabling faster access and improved performance compared to retrieving it directly from Redeam or the partner system.

GET/suppliers/{supplier_id}: Use to retrieve specific supplier details and avoid unnecessary load on the bulk endpoint.

Retrieve Products

GET/suppliers/{supplier_id}/products: Use this endpoint to temporarily store data in your system's cache, enabling faster access and improved performance compared to retrieving it directly from Redeam or the partner system.

GET/suppliers/{supplier_id}/products/{product_id}: Use to get specific product details. This should be the endpoint called instead of the bulk/list call to avoid unnecessary load

Retrieve Rates

GET/suppliers/{supplier_id}/products/{product_id}/rates: Use this endpoint to temporarily store data in your system's cache, enabling faster access and improved performance compared to retrieving it directly from Redeam or the partner system.

GET/suppliers/{supplier_id}/products/{product_id}/rates/{rate_id}: Use to get specific rate details. This should be the endpoint called instead of the bulk/list call to avoid unnecessary load

Pricing & Availability

GET/suppliers/{supplier_id}/products/{product_id}/pricing/schedule: Retrieves pricing data. For specific rate details, we recommend adding the rate_id in the request so you can get the response by the rate.

GET/suppliers/{supplier_id}/products/{product_id}/availabilities: Utilise this endpoint with start and end dates for range data. Use this endpoint to temporarily store data in your system's cache, enabling faster access and improved performance compared to retrieving it directly from Redeam or the partner system.

GET/suppliers/{supplier_id}/products/{product_id}/availability: Use for last-minute checks, especially with low inventory. This will avoid a hold or booking failure later. rate_id should be used in this kind of request.

Hold & Booking

POST/holds: Use to acquire a hold. Holds will become required in the specifications in the near future.

GET/holds/{hold_id}: Using the hold_id you can query this endpoint and get the same transaction details returned in the POST/holds call.

DELETE/holds/{hold_id}: As a best practice process, we recommend to use this endpoint to release the hold when no longer needed. This will release the inventory and make it bookable again instead of waiting for it to be automatically released after the holdable time is reached.

POST/bookings: Confirmation of booking after the hold was placed so the details of the booking cannot be modified from the hold, if different it will cause the booking to fail, even if the requested product is available.

GET/bookings/{booking_id}: By querying this endpoint with the booking_id you will get the same transaction details returned in the POST/booking call

• When you, the Reseller supports 202 responses they need to send HTTP GET booking requests periodically for the completion status of the job. The response from said API will inform the current status of the booking operation

PUT//bookings/cancel/{booking_id}: To cancel a booking, the booking_id is required. Please note that some suppliers do not allow cancellations initiated by the customer or by you, the Reseller, through the API. For these suppliers, products or rates are set with cancelable = false.

Caching Recommendations

Effective caching reduces load on the API and improves integration performance. Here are the recommended caching intervals:

Suppliers, Products and Rates Caching

Get Suppliers → 1 time a day

Get Products → 1 time a day or as products are added to your system if you are manually mapping.

Get Rates → 1 time a day or as products are added to your system if you are manually mapping.

Some operator might change their data with more frequency so we recommend you to build their system to be able to support that if needed.

Availability and Pricing Caching Strategy

Adapt caching frequency to specific timeframes to maintain up-to-date data while minimizing system load. These timeframes establish intervals where caching rules are fine-tuned to balance performance efficiency with data accuracy:

• 3+ months: Cache once every 2 weeks.
• 1–3 months: Cache weekly.
• 1–3 weeks: Cache daily.
• 1–3 days: Cache multiple times daily.

It is recommended that you update availability and pricing at the same interval to maintain data consistency.

Instead of updating on a fixed schedule, Redeam's Notification API can alert you when information has changed - significantly reducing the number of outbound calls!

Important Data Considerations

When integrating with the Redeam API, it’s important to note that not all data fields are guaranteed to be included in the API responses. The inclusion of data depends on the information Redeam receives from Operators or Ticketing Systems. However, when the data is shared, it often contains important information that should be utilised effectively to ensure a robust user experience and functionality.

• Validate Data Presence: When data is shared, ensure your application uses it effectively. This includes presenting important details to users (e.g., supplier addresses, attraction hours, or product-specific information) and leveraging it for enhanced functionality.
• Design for Flexibility: Check for data inclusion but also account for scenarios where specific fields may not be shared in the response. Ensure your application can adapt by implementing a logic that accommodates both cases - when the data is present and when it is not - without compromising the user experience.

Supplier Location vs. Product Location

Supplier head office addresses are found in the GET Suppliers response, while attraction-specific addresses are in the GET Products response.

Supplier Hours vs. Product Hours vs. Rate Hours

A Supplier can have hours details at all those 3 different levels or have the same values for all of them. It could be a product with the corresponding operating hours and then have rates under it with the specific hour times that the rate is valid for.

These hours are for informational purposes only and do not correspond to availability.

Rate minTravelers & maxTravelers

This field represents the minimum and maximum number of travelers to qualify for this rate which means the maximum number of tickets that can be purchased for this rate. The data is being mapped from the Supplier setup. This will prevent customers from selecting more than the allowed quantity and getting errors during Hold and Booking requests.

Rate travelerTypes, ageBand and modifier

Support list of ageBand to describe a particular age or occupation of a traveler type

• Ideally, being able to consume the name and modifier to support the full breadth of price/traveler types the operators provide. These could be things like EU_CITIZEN, MILITARY

• Minimally support all age bands in the specifications ADULT,ANY,CHILD,INFANT,SENIOR,STUDENT,YOUTH

  • The ANY type may be used instead of the above listed ageBand, if distinctions between age or occupation are not relevant to the product. It’s a generic ageband type used by some suppliers and it’s recommended to be supported, otherwise, a workaround needs to be done to map that value.

• Solve multiple instances of the same age band. There are instances where operators will send 2 prices for the same traveler type (ie 2 - ADULT). This typically means there is a difference in the name/modifier that makes it a different traveler type still limited to adults OR it means they’re running a special price for a limited time. You can:

  • Consume name/modifier and display both
  • Display only one lower or higher of the 2 prices

Freesale and Reserved

Being able to handle both types of product rates gives you, the Reseller, the flexibility to manage both general admission (FREESALE) and time-slot defined (RESERVED) types. This allows you to accommodate a broader range of use cases for different suppliers and their connected products.

Timezones and Datetime formats

To know the local timezone value, you should check the timezone field under the Rate (rates.hours.timezone). Within Redeam, we do a hierarchical check order to verify the rate, product, and supplier timezone, if not present at any of these levels Redeam defaults to UTC at that point.

These hours are for informational purposes only and do not correspond to availability.

Redeam Availabilities endpoint response start and end times will return the information in Zulu, with a value like 2023-10-06T11:00:00Z; check the timezone field on the rate response to convert availability into the appropriate timezone. If this conversion is not done, pricing and availability could return inaccurately, especially for those suppliers in a timezone that borders the end of day UTC.

Notification API

Redeam strongly recommends implementing the Reseller Notification API. This interface pushes notifications to resellers, indicating when data has changed through Redeam's APIs. Resellers can then update the appropriate objects within their own cache, reducing dependence on frequent cache updates.

Managing IDs

Avoid Hard-Coding IDs: Product and Rate IDs are more consistent but are subject to change. RatePrice IDs will change frequently as the operators change things in their system. Instead of hard coding, use real-time data or configurable mappings.

RatePrice IDs: Especially prone to frequent updates.

• Use dynamic mapping by fetching RatePrice IDs in real-time from the API whenever needed. This ensures that the IDs are always up-to-date, reducing the risk of errors in your integration. For example, retrieve RatePrice IDs from the GET /Price Schedule endpoint when displaying pricing options to users, or as part of your nightly caching routine.
• Or configurable mappings by implement a mapping layer in your system that allows IDs to be updated from the API periodically and mapped to internal configurations. Example: Maintain a database of RatePrice IDs for each product and supplier, refreshing the data frequently.

Redeam tries to evaluate and recommend the Product/Rate levels for each operator. This should yield consistency across operators. However, some operators choose to map their products/rates at different levels because of availability and pricing options in their own systems, therefore, we recommend that you build flexibility into your Supplier, Product, Rate mapping if you are mapping to internal content and IDs.

Use multiple extension keys at the different levels

Redeam highly recommends you to implement all of the extensions, in all API request and response levels, in order to get the required data from the Operator / Ticketing System to have the complete set of information needed for bookings and tickets/vouchers. This will give you a connection that will support the most number of Suppliers without customization. Extensions allow for the exchange of custom data between suppliers and you, the Resellers so implementation of these at all levels will provide a foundation to handle all custom scenarios in the future.

Even if they are not required for the first partner connection, additional development can be avoided when onboarding a new partner requiring additional information.

For example, booking.extension.supplier.reference is a mandatory field for any Supplier integration through the Ticketmaster ticketing system. All Resellers partners like you need to pull the data from this field - placed once the booking is confirmed - and send it through on the voucher. But it doesn’t mean this data is mandatory for Disney or any other Supplier connections.

See more information on the Extensions page.

Pricing and Availability

Last-Minute Availability Check

Use the GET /suppliers/{supplier_id}/products/{product_id}/availability endpoint for a last-minute check, especially for products with low inventory ( rate_id should be used in this kind of request). This helps avoid hold or booking failures.

Last-Minute Pricing Check

Use GET /suppliers/{supplier_id}/products/{product_id}/pricing/schedule for a last-minute pricing check. This can be set as a configurable option based on transaction volume. Your Redeam Implementation manager can tell you if a particular supplier changes pricing frequently. This will avoid a hold or booking failure later.

Price Schedule vs. Rates

Get Price Schedule needs to be implemented in conjunction with the Get Rates call, one does not replace the other, you must support both to get all the details needed.

Implement Price Schedule with the ability to identify and properly use the pricing types: net, retail, original. net and retail should be considered at a minimum and should be used appropriately and according to your contracts with your operators. If your system does not support the use of both retail and net, please let your integration manager know as Redeam can set up pricing rules to provide the type of rates that you need per operator.

Ensure price amounts (original, net, retails) and priceId used are always the ones from the price schedule response

Redeam added a header to the GET Rates / GET Rate Reseller API request to allow the Resellers to opt into a new treatment of missing dollar amount information on Rate Prices, by adding a request header to their requests

• If you call with the X-Allow-Nil-Static-Prices=true header: those prices that were not provided by the Supplier will have nil values explicitly. If you see product rates with $0.00 amount on any or all of Net, Retail and Original fields, it will be clear that the Supplier submitted the data intentionally that way.

  • In case the Supplier updates the price data and instead of nill they set an amount, it won’t create new rate ids, just price ids, which is the same behavior if the supplier updates their prices. The same could happen the other way around

• If the you call without the header: the new treatment of missing dollar amount information on Rate Prices won’t be applicable and you will continue to see it as $0.00 amount and won’t be able to discern the difference between a missing price vs a true $0.00 price.

Note that the same behavior is applied to Price Schedule endpoint and the embedded rates under booking items in Booking endpoint responses.

Create Holds before Bookings

If a rate is set as holdable=true then you must send a hold with the correct expires date time.

You can include multiple rates in a single hold as long as they are for the same supplier and products this will allow you to work with the varying ways that a supplier can build their data and streamline the booking process for a better end-customer experience. So the customer can book several rates under the same booking instead of having to make separate requests.

Also, you should pay attention to the hold times set by the Supplier prior to binding the products to ensure they are compatible with your system times, if not the case, updates might need to be considered on your end to determine the time that suits the Supplier SLA.

Barcode Format Considerations

Whether there is one or many barcodes in the booking confirmation, we map onto tickets.

You, the Reseller, need to know if for the specific integration, the Supplier will deliver a single barcode shared among all tickets in the Booking or if there will be a barcode for each ticket in the Booking.

A booking.extensions.beta-deliveryMethod field can be found in the booking response indicating to you whether this confirmed booking contains one ticket per-guest, (TICKET) or one ticket per-booking (VOUCHER).

Also, please note that for some integrations you might not get the actual scannable barcode in the booking response, instead there could be an instructions message, for instance, "Your tickets will be delivered no later than 2 weeks prior to the performance". That is because the Supplier or Ticketing System will send the tickets directly to the customer using the email address provided in the booking confirmation. It could be automatically after the booking confirmation or some time in advance of the date of the event.

HTTP 202 Responses

If you and the operator support pending booking functionality, an HTTP 202 response may be returned during the booking flow. Tickets will not be returned with a 202 response, instead, you must regularly fetch the booking ID from the GET Booking API endpoint to retrieve the confirmed tickets when the booking transitions from PENDING status to OPEN. This is recommended for those Resellers partners like you who want to connect to high volume systems or live event systems. These are the systems typically using 202 Pending booking responses.

• Redeam will send an HTTP 202 response with Booking status PENDING to the Reseller
• Reseller receives the usual Booking response JSON but without the tickets because it was not provided by the Supplier or Ticketing System yet
• Reseller needs to call Redeam GET Booking API to get the confirmation with the tickets details included in it. This could be within a few minutes or up to 24 hrs prior to the event.
• Once Redeam gets the confirmation from the Supplier or Ticketing System, the booking status will change from PENDING to OPEN and the Reseller will be able to see the tickets details returned in the booking response.