Skip to main content

Purchase flow tutorial

API Purchase flow tutorial​

Once you have all the information you need about your available events and sessions (see our Availability tutorials) it is time to start a purchase flow. To do so, you will have to follow seven simple steps (plus some optional ones):

  • Create a shopping cart
  • Add products to your shopping cart. These products can be added by means of:
    • adding best seats (automatic seat selection)
    • adding a manually selected seat
    • adding an activity or theme park ticket
  • Optionally removing one or all products from your shopping cart
  • Add your customer data to the shopping cart
  • Setting a delivery method
  • Create an order
  • Commit the order
  • Get the tickets from the order
Let's get started with the examples

Step-by-step examples​

This guide shows how to implement a complete purchase flow step by step.

Prerequisites!

You will need a valid OAuth access_token to be able to make each call! Please refer to our Authentication Guide to obtain one.

Create a new shopping cart​

First of all we create a new shopping cart. This shopping cart will be the "basket" or "holder" that will contain all the data required during the buying process. All the interactions of your customer should be reflected in the shopping cart. For more information about a shopping cart, please refer to our glossary.

curl --location --request POST 'https://gateway-pre.oneboxtickets.net/onebox-rest2/rest/shoppingCart/create' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data-raw ''

This call will return an empty shopping cart. The token attribute is the shopping cart unique identifier that you will use in the rest of the calls. Important: a shopping cart will expire after 10 minutes of inactivity. Once the shopping cart has expired, it will release all it's products and be permanently deleted. Tip: some http client will not let you make a post call without body, that's why we send an empty body on this request.

Add products to your shopping cart​

In this section we give you several examples of how to add a product to your shopping cart. All of these calls have two common points:

  • session-id: The id of the session (performance) or time span (of an activity) that the customer wishes to attend.
  • cart-token: The shopping cart identifier.

Let's see the different examples:

Add best seats to shopping cart​

This example lets you add a seat without knowing which seat will be added. The selection of this seat will be delegated on an algorithm of our API that will infer the best seat possible based on the characteristics of the venue where the session will take place. You can add more than one seat at the time. The parameters are:

  • session-id The id of the session this seat belongs to.
  • amount-of-seats: the amount of seat you wish to add to the shopping cart
  • idRate: Use this parameter if you want to apply a rate to the seats (optional).
curl --location --request POST 'http://gateway-pre.oneboxtickets.net/onebox-rest2/rest/shoppingCart/addBestSeats' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {{access_token}}' \
--data-urlencode 'idSession={{session-id}}' \
--data-urlencode 'numSeats={{amount-of-seats}}' \
--data-urlencode 'idRate={{id-rate}}' \
--data-urlencode 'token={{cart-token}}'

This call will return an updated shopping cart with the added seat(s) (if successful).

Add manually selected seats to shopping cart​

In order to make this call you have to previously identify a seat in a given session. Once you have that information you can simply call this endpoint with the following params (please notice that the params are enclosed in an XML structure):

  • seat-id: The identifier of the selected seat
  • session-id The id of the session this seat belongs to.
  • idRate: Use this parameter if you want to apply a rate to the seats (optional). Notice that the XML structure accepts a list of seats and session. In theory, you can add several seats of different sessions, but this is a very uncommon practice.
curl --location --request POST 'https://gateway-pre.oneboxtickets.net/onebox-rest2/rest/shoppingCart/addSeats' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {{access_token}}' \
--data-urlencode 'seatsList=<?xml version="1.0" encoding="UTF-8"?><seatsList xmlns="http://www.oneboxtm.es/ns/input-data/shopping/cart"><seat xmlns="http://www.oneboxtm.es/ns/input-data/shopping/cart" id="{{seat-id}}" sessionId="{{session-id}}" /></seatsList>' \
--data-urlencode 'idRate={{id-rate}}' \
--data-urlencode 'token={{cart-token}}'

This call will return an updated shopping cart with the added seat(s) (if successful).

Note: In case the session is numbered it is necessary to use this endpoint to add the seats to the cart manually, but if the session is not numbered it is recommended to use the previous call (Add Best Seats) for its simplicity of use, see how to know if a session is of numbered type or not in our guide of how to obtain session information.

Add Activity Seats​

Adding an activity seat is very similar to adding a seats with the add best seats call, with the only difference that we must specify the activity ticket type. Each activity might have one or more types of types (ie: regular, preferential, premium) to choose from. The key parameters in this case are:

  • session-id The id of the session this seat belongs to.
  • activity-ticket-type-id: the id of the activity ticket type we choose.
  • amount-of-seats: the amount of seat you wish to add to the shopping cart
  • idRate: Use this parameter if you want to apply a rate to the seats (optional).
curl --location --request POST 'http://gateway-pre.oneboxtickets.net/onebox-rest2/rest/shoppingCart/addIndividualActivitySeats' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {{access_token}}' \
--data-urlencode 'idActivityTicketType={{activity-ticket-type-id}}' \
--data-urlencode 'idSession={{session-id}}' \
--data-urlencode 'numSeats={{amount-of-seats}}' \
--data-urlencode 'idRate={{id-rate}}' \
--data-urlencode 'token={{cart-token}}'

This call will return an updated shopping cart with the added seat(s) (if successful).

Remove some or all products from your shopping cart (optional)​

You can optionally remove some (or all products) from you shopping cart. To do so, you must make the following call wih the given params:

  • item-id: the id of the item to be removed. This id must be valid and IN your shopping cart at the moment of the call. You can send more than one item id, but they cannot be duplicated.
curl --location --request POST 'http://gateway-pre.oneboxtickets.net/onebox-rest2/rest/shoppingCart/releaseItems' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {{access_token}}' \
--data-urlencode 'token={{cart-token}}' \
--data-urlencode 'items={{item-id}}' \
--data-urlencode 'items={{item-id-x}}'

Optionally you could choose to remove all products in the shopping cart with the following call:

curl --location --request POST 'http://gateway-pre.oneboxtickets.net/onebox-rest2/shoppingCart/releaseAllItems' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {{access_token}}' \
--data-urlencode 'token={{cart-token}}'

This call will return an updated shopping cart with the added seat(s) (if successful).

Important: removing all items of your shopping cart will not clear the customer data.

Add Client Data​

Before finishing an order, you must specify the customer this order belongs to. there are several attributes you can specify for a customer as described in our glossary. The mandatory fields you will need in order to complete the order are:

  • customer-email (REQUIRED): a valid email that will identify the customer for this order. This email can be later use to track the order in our backoffice application.
  • customer-first-name: The name(s) of your customer. Please bear in mind that some special characters might be removed from this field (such as emoji) if they are sent.
  • customer-last-name: The name(s) of your customer. Please bear in mind that some special characters might be removed from this field (such as emoji) if they are sent.
curl --location --request POST 'http://gateway-pre.oneboxtickets.net/onebox-rest2/rest/shoppingCart/clientData' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'email={{customer-email}}' \
--data-urlencode 'firstName={{customer-first-name}}}' \
--data-urlencode 'lastName={{customer-last-name}}' \
--data-urlencode 'token={{cart-token}}'

This call will return an updated shopping cart with the added data (if successful).

Note: The only mandatory client data field parameter is the email but there is also an extensive list of fields that can be sent opcionally, you can review the complete list in the following link: Client Data Available Field Paratemeters

If for some special need the integration need to send an extra custom field, once the integration have access to the production environment is possible to request it from our operations team and they will enable it for the channel.

Setting the delivery method​

Setting the delivery method is required for our platform. Here we specify the most common case (an the one you will be using) that is setting the delivery method via email (type 1). There are other delivery methods, but they are uncommon for an API integration.

curl --location --request POST 'http://gateway-pre.oneboxtickets.net/onebox-rest2/rest/shoppingCart/delivery' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {{access_token}}' \
--data-urlencode 'orderDeliveryCost=0.0' \
--data-urlencode 'type=1' \
--data-urlencode 'token={{cart-token}}'

Important: Onebox will not send an email to your customer, this must be done on the integrating part. This call will return an updated shopping cart with the added data (if successful).

Getting the shopping cart details​

Optionally you can review the details and the content of the Shopping Cart before create the order, learn how to do it easily in our Shopping Cart Details guide.

Creating an order​

Once your customer has selected all the desired products and fulfilled their data, it's time to create an order. An order is longer lived than a shopping cart and allows your customer to fulfill the payment without the risk of loosing their selected items. But eventually an order will expire after 45 minutes (depending on the type of products in your order this might vary) if not properly confirmed.

curl --location --request POST 'http://gateway-pre.oneboxtickets.net/onebox-rest2/rest/order/createOrder' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {{access_token}}' \
--data-urlencode 'orderType=PURCHASE' \
--data-urlencode 'token={{cart-token}}'

This call returns an order with an order code in it's locator field. This order code is the one needed to commit the order and will not change afterwards. If the order expires, all of it's products will be released and it will be permanently deleted.

Order Confirmation​

After you have the certainty that your customer has fulfilled the payment, you can confirm the order. The key elements are the order code and a list of payments (please notice that the list of payments are enclosed in an XML structure).

  • order-code: the identifier of the order you wish to confirm
  • payment-type: the type of payment this amount belongs to. Could be CASH, CREDIT_CARD or others, please check our glossary for more types.
  • paid-amount: the amount of this payment. There can be several payments, but the addition of all the amounts must match the order total amount.
curl --location --request POST 'http://gateway-pre.oneboxtickets.net/onebox-rest2/rest/order/commitOrder' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {{access_token}}' \
--data-urlencode 'orderCode={{order-code}}' \
--data-urlencode 'payments=<payments xmlns="http://www.oneboxtm.es/ns/input-data/purchase/order"><payment xmlns="http://www.oneboxtm.es/ns/input-data/purchase/order" type="{{payment-type}}" value="{{paid-amount}}"/></payments>'

Get Tickets PDF​

After completion of an order you can get the generated PDF tickets to send the to your customer by making the following call. In this call the main parameter is:

  • order-code: the order for which you wish to retrieve it's tickets.
curl --location --request GET 'http://gateway-pre.oneboxtickets.net/onebox-rest2/rest/order/ticketsPDF?orderCode={{order-code}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}'