Purchase Flow Alignment

API Purchase flow integration alignment

We have several public API, one of them is a Ticket Distribution API that will let you check for availability, book and finally get the tickets.

General booking flow

It is based on four main steps:

  • Inventory contents and availability, can be numbered or not numbered.
  • Add tickets to a shopping cart and manage them and with its available promotions and discounts.
  • Confirm an order, and take into account the payment process at your end.
  • Get tickets or just retrieve the information needed to make yours.

And two kind of products: Events and Activities.

  • Events as products with one or more dates and timings scheduled which can be performed in a numbered or not numbered venue (Theaters, live music, sports).
  • Activities, a not numbered event which it is going to be repeated within a certain period of time (museums, theme parks).


Attendant fields (event with attendant tickets)

For some events it will be necessary to add information regarding the event attendant.

  • To know if you should request this information from the user, you must verify that the attribute "mandatoryAttendant" has the value "true".
  • To obtain the necessary fields for the assistant, you must make a call to /event/{idEvent}/eventField?fieldGroup=EVENT_ATTENDANT. These fields must be requested from the client just before creating the order.
  • An example of what a call would be like to add the assistant fields to the shopping cart is detailed below.

Let's take a look at each case in more detail:


Activities (Not numbered) integration funnel

General booking flow
Contents And Availability Shopping Cart Purchase Order Get Tickets
  • /event/search
  • /event/{id}/info
  • event/{eventId}/eventField **
  • /session/{id}/info
  • /shoppingCart/create
  • /shoppingCart/addInfividualActivitySeats
  • /shoppingCart/releaseItems
  • /shoppingCart/availablePromotionsAndDiscounts
  • /shoppingCart/addPromotion
  • /shoppingCart/addDisconunt
  • /shoppingCart/releasePromotion
  • /shoppingCart/releaseDiscount
  • /shoppingCart/clientData
  • /shoppingCart/addAttendant **
  • /shoppingCart/delivery
  • /order/createOrder
  • /order/commitOrder
  • /order/details
  • /order/ticketsPDF
  • /order/ticketsInfo
  • Download product catalogue

    As an activity is a not numbered event which it is going to be repeated within a certain period of time (museums, theme parks), you only need to implement three calls in order to get the product and check for its availability.

    • /events/search - To retrieve the entire product catalogue for the given on sale channel including events and its session performances. Must be filtered by eventType=ACTIVITY
    • /event/{id}/info - To get event detailed information.
    • /session/{id}/info - This let you check the availability for the given performance.
    Notice that the order of parameters matter and it must be in alphabetic order. In example:
    • /events/search?endDate=2017-05-05&eventType=ACTIVITY&eventType=EVENT&startDate=2016-12-01

    Availability check

    In order to check a performance availability by calling /session/{id}/info, you will have to pay attention to activity-ticket-type-availability attribute, taking into account:

    • Null or empty value, means unlimited availability.
    • 0 value, means no availability.
    • Numeric value distinct from 0, means there is a quota available.

    Shopping cart

    First of all, an empty shopping cart must be created by calling /shoppingCart/create method which returns a token unique identifier. After that, you will have to use it in order to add/remove seat tickets to the cart.

    Bear in mind whilst a shopping cart is active, any ticket into it is locked up to 10 minutes to ensure nobody else could buy them as well. In case that time expires without an order has been created, the tickets will be automatically released and will be available again.

    • Just in case of activities, there is an specific endpoint to add activities seats: /shoppingCart/addInfividualActivitySeats
    • It's mandatory to send all the client data using /shoppingCart/clientData endpoint. The data to send is email, full name, address, zip code, city, country (ISO standard code, you can obtain it calling to the /masterData/countries endpoint, for example, for Spain country is countryCode=ES)and telephone.
    • For delivery method (shoppingCart/delivery), you have to send the delivery type, the possible types are:
      1. Print at home, you send the tickets by email to the customer.
      2. Will Call, to pick up at the event's venue.
      3. Print express, you print the ticket in the sale moment.
      4. Mobile, you use some mobile delivery method.
      5. External delivery, the channel manages the delivery.
      6. National Postal, the delivery is done by national mail.
      7. International Postal, the delivery is done by international mail.
    In addition, it is also feasible to manage promotions and discounts over a shopping cart. Our promotions are bounded to the number and type of selected tickets into a shopping cart, so that we provide service calls to check available promotions, apply it or remove it.

    Process and order

    Once the shopping cart is complete it should be turned into an order to be able to confirm the booking. This have to be performed in two steps in order to let you handle with the payment at your end. First call is /order/createOrder which one will increase the seating lock time up to 45 minutes, which is the time you will have to process that payment, and then a call to /order/commitOrder must be done to finally confirm the booking.

    The payment processes have to be implemented at your end but at least you have to notice the amount already paid in the /order/commitOrder call and ensure this is greater or equals from the order total price amount.

    Retrieve the tickets

    The process ends with the download of the tickets, here you can choose between our pdf tickets (/order/ticketsPDF) or to create your own tickets from the information provided by /order/ticketsInfo. Take into account that the venue/organizer will be the one who will define the ticket template for an event.

    Integration timings

    Usually an integration of activity events which always are a not numbered event, does take about 60 days from scratch to go live.

    Just in case you would like to add promotion or discounts capabilities, bear in mind this might take about 30 days more of development.


    Events (Not numbered) integration funnel

    General booking flow
    Contents And Availability Shopping Cart Purchase Order Get Tickets
  • /event/search
  • /event/{id}/info
  • event/{eventId}/eventField **
  • /session/{id}/info
  • /shoppingCart/create
  • /shoppingCart/addBestSeats
  • /shoppingCart/releaseItems
  • /shoppingCart/availablePromotionsAndDiscounts
  • /shoppingCart/addPromotion
  • /shoppingCart/addDisconunt
  • /shoppingCart/releasePromotion
  • /shoppingCart/releaseDiscount
  • /shoppingCart/clientData
  • /shoppingCart/addAttendant **
  • /shoppingCart/delivery
  • /order/createOrder
  • /order/commitOrder
  • /order/details
  • /order/ticketsPDF
  • /order/ticketsInfo
  • This is basically the same flow as Activities (not numbered) with just a couple of particularities:

    • /events/search?eventType=EVENT, it is mandatory to set event the event type to EVENT.
    • /shoppingCart/addSeats, there is an specific call to add ticket seats of type EVENT to a shopping cart.

    Integration timings

    Usually an integration of not numbered events does take about 60 days from scratch to go live.

    Just in case you would like to add promotion or discounts capabilities, bear in mind this might take about 30 days more of development.


    Events (Numbered) integration funnel

    General booking flow
    Contents And Availability Numbered Shopping Cart Purchase Order Get Tickets
  • /event/search
  • /event/{id}/info
  • event/{eventId}/eventField **
  • /session/{id}/info
  • /session/{id}/seatMap/rootView
  • /session/{id}/seatMap/view/{id}
  • /session/{id}/seatStatus/{id}
  • /shoppingCart/create
  • /shoppingCart/addSeats
  • /shoppingCart/addBestSeats
  • /shoppingCart/releaseItems
  • /shoppingCart/availablePromotionsAndDiscounts
  • /shoppingCart/addPromotion
  • /shoppingCart/addDisconunt
  • /shoppingCart/releasePromotion
  • /shoppingCart/releaseDiscount
  • /shoppingCart/clientData
  • /shoppingCart/addAttendant **
  • /shoppingCart/delivery
  • /order/createOrder
  • /order/commitOrder
  • /order/details
  • /order/ticketsPDF
  • /order/ticketsInfo
  • Starting from the Events (not numbered) flow, just in case of a numbered event you will be able to handle with the manual or automatic seating selection. In order to do that the API is exposing several endpoints more as follows:

    • /session/seatMap/rootView, information to related to the graphical representation of the first venue tier. It can contain links to other views.
    • /session/seatMap/view, this provide information about the following venue tier levels in order to let you navigate the venue as a tree. It can contain links to other views.
    • /session/seatsStatus, retrieve the information on the status and availability of the given view (numbered seats, unnumbered areas and summary of the link status).
    • /shoppingCart/addSeats, this let you indicate the specific seats you wish to lock into a given shopping cart so you must already know the seating map of the venue.
    • /shoppingCart/addBestSeats, in this case the selection is delegated to our intertal algorithms which will perform the best seating allocation on your behalf. You do not have to know the venue mapping before, you just need to know the price zones map.

    Integration timings

    This integration which includes the full set of Onebox services, normally does take more than 6 month from scratch to go live.

    ** This end point is necessary only when it is an event with assistant fields.


    Order payment integration

    General booking flow

    In Onebox the order booking action is performed in two steps (to create the order from a shopping cart and then confirmation of the already created order). This is to let you manage the payment at your end as you need.

    • /order/createOrder, create a new order from a given shopping cart.
    • /order/commitOrder, confirm an active order. If the order expires its tickets will be released and it won't be committed at all.

    Just take into account that the lock time of the seats will be increased up to 45 minutes from the shopping cart previous lock time, should be enough time to let you handle with the payment.

    Once the payment it's done, it's mandatory to send the order code which belongs at your end. For it, use /order/commit endpoint and externalCode parameter.

    To obtain tickets, ONEBOX API offers a endpoint that you have to indicate it orderCode obtained in the commit.

    • /order/ticketsPdf, get access's url where you obtain the tickets.
    • /order/ticketsInfo, obtain info about tickets generated.

    Notice that, you have an expiration time (5 minutes) indicated in Expires property to obtain the pdf.

    You have to retry the call each 1-2 seconds (recommended). The generation process is an asynchronous process, so if the ticket hasn't been generated, the API really returns 1088 - ERROR_REST_ORDER_TICKETS_IN_GENERATION_PROCESS (502 gateway error). Once that the ticket is generated, the API returns the URL to access and 200 HTTP status code.

    You can manage this putting a limit of 5 retries and each retry does it with 1 second delay while you don't obtain response 200 HTTP status code, for example.

    To refund an order, you have to call the order/refundItems endpoint indicating the order code, the payment, the items (tickets) that you want to refund and if the charges is included. There are more parameters, you can study the complete documentation in this link Documentation: Refund an order

    • includeCharges, boolean value indicating if the charges are included.
    • items, list of items (tickets) to refund (for example: items=1&items=2...).
    • orderCode, the order code that you want to refund.
    • payments, xml structure like this:

      Notice that the value have to be the import of the items.

    Important note about refunds: to refund orders throught the API, there must be an agreement with the event's promoter.


    Widget integration

    General booking flow

    The Onebox Widget is a utility which offers graphic functionalities to do seating selection in an easy way, using renders from Onebox's system, and also allow you to manage promotions linked to the selected seats. The widget is a responsive component which will be able to adapt to any device's screen.

    The scope of the widget is market in pink on the diagram below, starting from the graphical navigation, passing through the seating selection and finally managing any promotion and discounts that could be applicable:

    • Seating selection
    • Apply promotions
    • Responsive component, adaptable to all devices
    • Configurable
    • Graphic Venue and non-graphic Venue (numbered / not numbered)

    Let's see the support files section to get more information on how to integrate it or contact api-support@oneboxtm.com

    Integration timings

    Widget integration time is about a couple of weeks as an average development time.