Quick Start
This is a quick guide to get you up and running to make API calls. The Xola API is organized around REST principles. So a HTTP POST will create a resource, a PUT will update it, a GET will retrieve it and a DELETE will delete it. Most API end points need you to be authenticated to perform the operation. All API payloads are in JSON, and responses are in JSON only.
Create your account below. If you already have an account, skip down to "Get your API Key".
Sandbox accounts do not carry over to Production
Most of our documentation provides examples for our Sandbox environment (sandbox.xola.com). Any credentials or resources you create in Sandbox will not carry over to Production (xola.com). You'll need to create a separate set of credentials for the Production environment.
Create a new account
New accounts are created via a POST request to the users API end point. The email address should be a valid address that will receive a confirmation email.
curl -H "Content-type: application/json" -X POST https://sandbox.xola.com/api/users -d '{
"name" : "John Doe",
"email" : "[email protected]",
"password" : "password123",
"roles" : ["ROLE_DEVELOPER"]
}'
If you plan to make API calls on behalf of a seller, then the roles attribute is optional. However, the seller will have to grant you access to their API through the "Grant Access" section in the Xola seller interface.
Confirm Your Email Address
Once the account is created, click on the activation link in the email to proceed ahead
Get your account information
Grab your user account ID and check up on your roles. Make note of your user id, as that will be used to get your API Key
curl -H "Content-type: application/json" https://sandbox.xola.com/api/users/me -u "[email protected]:password123"
Get your API Key
curl https://sandbox.xola.com/api/users/<my_user_id>/apiKey -u "[email protected]:password123"
All future requests don't need username password. You can use the API Key, for example - getting your user info
curl -H 'X-API-KEY: MYAPIKEY' https://sandbox.xola.com/api/users/me
Fetch Experiences
Fetching all experiences available to you requires being authenticated
curl -H 'X-API-KEY: MYAPIKEY' https://sandbox.xola.com/api/experiences
No auth is required for fetching information about a specific experience
curl https://sandbox.xola.com/api/experiences/4f358f70536e86b149000000
Refer to the detailed documentation in the Orders section below to know more.
Below you will find every API end point available to you.
Terminology
There are three key objects in Xola that every API developer should know about. We'll use flight tickets as an analogy here to explain what each term means.
- Experiences - An experience is also known as a listing. These are items that your customers purchase. For example: Delta Airlines offers a flight from NYC to LA. This is Delta's experience/listing.
- Orders - A customer will make a booking for a specific experience, they're essentially purchasing something. For example.: A customer buys a flight ticket for Delta Airlines flight 447 from NYC to LA. The customer has given money and it has created a booking in Delta's flight reservation system. This is an order.
- Transactions - A transaction is something that tracks movement of money in Xola. If the traveler paid $100 via credit card for a booking, that will be logged as a transaction. Then two days later they want to buy an add-on (merchandise) like a T-Shirt for $20, this would be logged as a second transaction. Any exchange of money, through any payment method (credit card, cash, check) is logged as a transaction. This way you can always track who paid what, when and how.
Payment Methods
Xola has built in support for several payment methods. Each payment method is used when creating a booking, or collecting payments on a booking.
The default payment methods are:
cc
Credit Card - This payment will be processed through the account's payment gateway.
cash
Any Cash payment
check
A payment through any type of check
gift
A gift certificate purchased through Xola
affiliate_deposit
Affiliate Deposit. This indicates the payment was given to an affiliate.
voucher
A voucher (with a voucher code)
later
Pay Later. This indicates payment is not collected not, and will be collected later.
other
Other -- A generic payment method to support any payment method not reflected above
Each key above (like cc or cash) can be used in API calls when referencing a payment method.
You might find the "Other" payment method is too broad and does not precisely describe what some frequently-used methods of payment might be (e.g. credit card terminal; imported bookings, etc). To solve this problem Xola provides the ability to create custom payment methods. Each custom payment method can have a name like "Credit Card Terminal" or "Square POS" and they will have their own 24 character ID, you can use this ID in lieu of the above default payment methods when collecting a payment.
For details see the API end point reference.
Booking Sources
Every order and transaction has a source attribute. The source indicates what type of application was used to create the order or transaction. The possible sources are:
office
The Xola back office application at /seller
checkout
The traveler checkout application. Usually through a "Book Now" button
refund
A refund transaction usually done through the back office
xola
A transaction created by Xola. Usually for monthly subscription charged.
import
An order or transaction created through an import process. These are orders that are usually created when a seller has pre-existing orders that need to be batch imported
Metadata
Certain objects in Xola have a metadata parameter. You can use this parameter to attach key-value data to these objects.
Metadata is useful for storing additional, structured information about an object. For example, you could store the customer ID from your CRM system in the Xola User object.
One important limitation of metadata keys is that they cannot contain periods (.). We recommend you use a forward slash (/) to delimit keys.
We also recommend that you namespace your keys by prefixing them with your company name and application name so that your keys do not conflict with any other applications that may utilize metadata. E.g. acme/rocket/my_preference
Currently, the following objects support user-definable metadata:
Users
POST /api/users/:id/metato add metadata. You may pass multiple key-value pairs.DELETE /api/users/:id/meta/:propertyto remove a single metadata property.
Any metadata present for a user will be returned when fetching a user with the private=true flag.GET /api/users/:id?private=true
Introduction
Experiences also known as "Listings" are the experiences and activities that the seller's business offers. The experiences end point is where you create & update experience, and it is where you update logistical information like trip schedules, pricing, and trip logistics like duration, capacity, and location.
List categories
A category is a structured field that must be present in all experiences.
List all experiences
This endpoint is great for discovery operations and is typically the starting point for any consumer focused app. It allows querying Xola's database of experiences using a variety of interesting data filters.
This endpoint is best used as an authenticated user
Remove an experience
Deletes an experience, which prevents it from being booked. Existing bookings with the deleted experience will remain unaffected
Medias
A media item represents photos & other images that are associated with an experience. These maybe used as the primary photo for the experience, or as other photos that can be used to show off the experience to perspective travelers.
Retrieve media
Get an image for an experience
Returns an image for an experience. The filters allow you to resize the image on the server. If no filters are specified, the original image is returned unaltered.
The bg size returns a large image that is blurred which can be used as the background of a page displaying the relevant experience.
Upload Media
Upload a photo for this experience
The body of the request must contain the full raw data of the image
Attachments
Attachments are non-image related files like PDFs and Word documents. These attachments are usually sent as a part of the order confirmation email when a booking is created.
Add-Ons
Add-Ons are additional items that are sold along with a listing. They are set on a per-listing basis and you can add as many as you like. Add-ons can be customer-facing (so available to purchase during online checkout) or private (so can only be added to a purchase if it is a back office booking or modification).
The add-on structure is very simple. It has a name, a price, a description and a visibility flag.
{
"name": "Go-Pro",
"price": 15,
"desc": "A Go-Pro camera to record your trip!",
"visibility": "public"
}Demographics
These set of API end points represent demographics directly tied to a specific listing. You can modify listing specific demographics with the end points below.
To fetch a list of demographics for a single listing, just retrieve the experience directly.
Remove a demographic
Remove a demographic from an experience. When you remove a demographic from an experience it will no longer be shown when you create a new booking. Demographics in existing bookings are not removed.
Resources
Resources also known as inventory items are fixed resources that can be utilized across multiple listings. You must have the inventory feature turned on for this API endpoint to work.
There are two concepts in inventory items:
- Capacity: The capacity is how many people, seats, or units are in each piece of equipment. For example, if you have a bus, this would refer to how many seats you have on the bus.
- Count: The count refers to how many units of equipment you have. In our bus example, the capacity is 20 seats but if we only have 1 bus the count is 1.
Assign an inventory item to an experience
Note: You are restricted to only one inventory item per experience
Review Preferences
Review reminders are way to send automated emails to the traveler after their trip is completed reminding them to review the trip. Xola will send an automated review reminder email to the traveler 24 hours after the trip has completed. Xola gives you five review options:
- Xola (
xola) - Xola will our own email template and collect feedback that is stored privately - Google+ (
google) - Send an email to the traveler with a link to a Google+ page - TripAdvisor (
tripadvisor) - Send an email to the traveler with a link to a TripAdvisor page - Yelp (
yelp) - Send an email to the traveler with a link to a Yelp.com page - Custom (
custom) - Send an email with a custom email template that you write
Links for Google+, TripAdvisor & Yelp are taken from the social links in the seller's profile.
Add a review preference
Adding a review preference to an experience overrides one specified at a global (user) level.
Remove a review preference
Once a review preference is removed from an experience, any review preference configured at a global (user) level kicks in.
Schedules
This API end point allows you to build activity schedules that define when your trip departs. Combining schedules also allows for dynamic pricing that adjusts based on time or day. You can create as many schedules as you would like.
For each schedule you can configure how it behaves. The following attributes are available:
Schedule type:
available: Creates a schedule with times that this listing is available to be booked by customers.unavailable: Creates a schedule with times that this listing will not be available.
Schedule repeats:
weekly: Repeat the schedule every weekcustom: Specify specific days on which the schedule will apply
Schedule timeslots:
These are specific departure times that are able to be booked for this listing. You may create upto 100 timeslots. Specify the timeslots as an integer value (e.g. 800 for 8AM and 2200 for 10PM).
If your listing does not have set departure times, send varies for the departure attribute.
Schedule days:
These are specific departure weekdays (Sunday, Monday etc) that are able to be booked for the listing. The days are specified by an integer value representing the day of the week. 0 represents a Sunday, 1 a Monday and 6 for a Saturday.
Schedule start & end:
This is the time-span that the will apply to the schedule. If the schedule never changes, then you don't need to specify a value for this attribute.
Schedule price (price delta):
This will allow you to specify a price delta for this schedule. You can increase or decrease a price for a given schedule. For example: If you charge more for trips on the weekend, make a weekly schedule with Saturday and Sunday and specify a higher price
Whenever a schedule is successfully created or updated, the API will return an HTTP response code of 202. This is because the API updates the experience's schedules and does some additional post processing to update the dashboard. Depending on the number of trips the dashboard may take upto a minute to reflect the changes.
Remove a schedule
Remove a schedule from the experience. When you remove a schedule the experience won't be bookable on the date and time slots that were defined in it. Existing trips are not removed, they still remain.
Terms & Conditions
Terms and Conditions are a set of rules and guidelines that a user must agree to in order to place the booking. These are simply blocks of text that are shown to the traveler when they make a checkout, they maybe shown as a link or as a modal window specifically prompting the user to accept the terms. Terms & Conditions configured for this experience override any terms that are configured at a global (user) level.
These set of end points allows you configure an account set of terms and conditions which will take effect if the experience does not have configured terms.
Remove terms and conditions for an experience
Delete the terms & conditions for an experience. Existing bookings that have the terms and conditions will not be affected. If the seller has terms & conditions configured globally then those will take effect.
Introduction
In Xola availability represents the number of open seats that are available on a given experience at a specific date & time. If the availability is 0, it means the particular date & time cannot be booked.
API end points usually return availability between a given date range (max range is 62 days).
Experiences may be configured to be "all-day" or have specific "time slots". Based on the type of schedule, the response structure will be different.
For timeslot based schedules, the response will be a nested object structure with date, time, and availability properties:
{
"2013-08-05": {
945: 0,
1200: 3,
},
"2013-09-08": {
945: 11,
1200: 0
}
}For all-day schedules, the response will contain date and availability properties (no time property):
{
"2013-08-05": 3,
"2013-09-08": 11
}Any date or times not present in the response are considered closed, and may not be used for a booking.
Batch availbility
Fetch real time availability for several experiences
This end point returns you availability information across multiple experiences
Event capacity
Returns the capacity of an experience regardless of scheduled availability
Introduction
Sellers create coupons to offer discounts on bookings. There are two varieties of coupons which allow you to reduce the total booking value:
- Discount: These are your traditional dollar amount or percentage off coupons. They allow a seller to specify rules around which the coupon value is calculated.
- Unlock: Allows the consumer to specify an arbitrary order amount. Any discount value will be accepted as long as it does not reduce the total order amount below zero.
All coupons are applied to the order amount before tax.
Coupon Structure
Each Coupon object represents one campaign. Every coupon will have a name attribute indicating the name of the campaign for e.g. 'Xmas Discounts 2016', and within the campaign there will an array of codes any one of which can be used while creating a booking. A code is unique across all coupons and can only be used in one campaign.
Each coupon also contains an amount and a series of string variables like algorithm and type that describe how the discount is calculated. Coupon usage maybe restricted based on an arrival date schedule as defined by arrivalSchedule or based on the date the booking can be made, as defined in bookBySchedule.
A sample object maybe found in the documentation below
Rules to Calculate Coupon Discount Value
Discount coupons rely on the the type and algorithm attributes that determine how the coupon value is calculated.
- algorithm: Determines if the calculation treats the
amountas anabsolutevalue or apercentvalue - type: Determines if the calculation is applicable per person (
person) or a flat discount for the entire booking (discount)
List all coupons
Returns
Return all coupons based on the above filters. It will not return coupon codes but it will return total uses for all codes in this coupon in the uses attribute.
To retrieve coupons, either the seller or experience must be specified as a filter. Optionally you may specify arrival or arrivalTime filters to restrict the response to coupons that can only be applied to orders with the specified arrival date & time.
Create a coupon
Create a new coupon for an authorized seller
To create a coupon you must be logged in and authorized with a reservation role (ROLE_RESERVATION) with the seller for whom you are creating the coupon.
Delete a coupon
Remove a coupon
Deleting a coupon will not remove it from any pre-existing orders. It will remove the coupon from the seller's interface and prevent it from being applied to any further overs.
Codes
One coupon can have multiple codes. Each code is a unique alphanumeric string that can be applied to a booking.
A coupon code has the following key attributes:
codeAn alphanumeric string that has the code that can be applied to a booking. This code is case in-sensitive.statusA status of100will indicate an active code, and a status of400will indicate a voided code. Voided codes cannot be used on a booking.usesThe number of times this code has been usedordersA list of order IDs where this code has been used.
List all codes
Retrieve all codes associated with a coupon
This will return a paginated response that will contain all the codes for this coupon
Void a code
Prevents a code from being used further, while still keeping the coupon active
Voiding a code will not remove it from any pre-existing orders. It will mark the code as voided (status 400) in the seller's coupon list and prevent it from being applied to any further overs.
List all drafts
Fetch drafts for this seller. This is currently restricted to order drafts only
Introduction
A trip (event) represents a collection of bookings for one experience that departs at the same time. In Xola's seller interface trips are what's shown on the dashboard. A trip will have a start & end time and an (optional) guide assigned. An event is automatically created when a new booking is created.
Create an event
An event is automatically created when a new booking is created, so this endpoint can be used to create an event that has no bookings. This is usually done to assign a guide or modify it's max capacity.
Returns
A successful request will return you the created event. However, if the creation of the event fails, then the response may vary based on the HTTP response code.
A response code of 409 will indicate that the guide is already assigned to another trip that conflicts with this time slot. The response body will contain the conflicting trip
Update an event
Update an event's max capacity. This allows you to override the maximum trip capacity configured in the experience configuration.
Changing the max capacity will not override any inventory restrictions. This end point only supports updating the max capacity.
Assign a guide to a trip
Add a guide to an event. Only a guide manager (ROLE_GUIDE_MANAGER) can add guides to the event
Email roster to a guide
Send the trip roster to the seller & any assigned guides through email
Notes
Xola allows you to add notes to any event (trip). These notes will be associated with the trip and will be shown on the dashboard and the guide's roster. You can only add notes to a trip that has 1 or more confirmed bookings.
Introduction
A demographic represents a type of customer within your experience. Demographics allow you to define custom discounts and a description that can be displayed at checkout.
Some examples of demographics are:
- Adult
- Children
- Senior Citizens (with a 10% discount)
- Military Veterans (with a 10% discount)
List all Demographics
Retrieve demographics that are created across the entire seller account
A demographic can be of two types:
- Global Demographic - One that applies across an entire account. This is indicated in the response by
object: seller_demographic - Experience Demographic - One that applies towards a specific listing only. This is indicated in the response by
object: experience_demographic
Introduction
Gift certificates allows customers to purchase a specific activity, or redeemable dollar amount, for their friends or family. Whenever a Gift is purchased it generates a special code, and this code can be used to pay for any new or existing booking.
List all Gifts
This will return a paginated response that will contain all the purchased Gifts.
Purchase a Gift
Create a new gift certificate
Confirmation Email
A confirmation email with the Gift code will be sent after the purchase is complete. The destination of the email will depend upon the sendTo field, you may choose either the customer (the person buying the gift) or the recipient (the person receiving the gift). A copy of this email will also be sent to the seller.
Add Funds
Once the request is successful and a HTTP 205 is returned, you should retrieve the Gift again to get an updated version for your records.
Increase Balance
Increases the balance of a gift. This adjustment does not affect the total amount paid by the purchaser of the gift. Any change made will only affect the redeemable value of the Gift Code. This action is not intended to collect any payment i.e. a purchase transaction will not be created.
Decrease Balance
Decreases the balance of a gift. This adjustment does not affect the total amount paid by the purchaser of the gift. Any change made will only affect the redeemable value of the Gift Code. This action is not intended to collect any payment i.e. a purchase transaction will not be created.
Refund Payment
This will refund a specific amount on a gift certificate back to the customer
Introduction
A job is essentially any background work that Xola is doing for a particular seller. The /api/jobs endpoints will allow you to fetch all the jobs for this seller and check on their status.
A job is created when there is any change done that requires extensive processing which cannot be completed in the lifecycle of an HTTP request. For example, when a seller modifies a schedule it has the potential to affect one or more trips & the dashboard too, therefore Xola will create a job to check and update availability for all affected trips.
The following statuses are available for a job:
new
The job was added to the queue but has not been picked up by a worker.
processing
The job is being processed right now.
completed
The job has finished processing and any necessary changes have been made.
error
The job failed & error'ed out.
stale
The job has been running too long and has timed out. It may or may not have finished all necessary tasks. This should rarely happen.
List supported languages
Fetch a list of languages from which a seller can pick to support his content in
Introduction
Orders represent any bookings that are made on a seller's account. The API end points available for orders allow you to create, update or cancel any booking within a seller's account.
Every order has an integer status atttribute which describes the state of the booking. The general principle with statuses are:
- Status < 200 indicates a pending booking
- Status >= 200 & < 300 indicates a confirmed booking
- Status >= 300 indicates an unconfirmed booking, which are bookings that were usually cancelled or not accepted.
100
A pending booking. The traveler's card has not been charged yet, and the booking will not be counted as a part of trip till it is accepted.
101
A booking in a pending state due to a minimum configured on the listing. Once the trip meets the minimum, the status of this order will automatically change to 200.
103
An order in a hold status.
200
A confirmed/accepted booking
201
A confirmed booking for which only a deposit has been collected
202
An accepted booking which has not been charged.
203
An accepted booking, but with the "Pay Later" payment method.
700
Booking has been canceled.
List all orders
This will return a paginated response that will contain all the orders.
Create a new Order
To create a confirmed order, you need to be logged in and be authorized with the reservation role (ROLE_RESERVATION or ROLE_RESERVATION_LITE) for the seller you are creating the order for.
Possibly the most complicated piece about orders are it's adjustments. Adjustments serve two purposes:
- Redundancy check: This formula should always be true
baseAmount + addOns + adjustments = amount - Audit trail: All changes to an order must be done via adjustments
You can use the /api/orders/prepare endpoint to have the adjustments generated for you.
Prepare an order
Use this endpoint to generate all the necessary "adjustments" for an order you want to create. This also returns a user friendly breakdown object that you can display to the consumer placing the order.
Adjustments
Adjustments are one of the key pieces in an order. They are essentially an audit trail of changes made to a booking by the traveler, seller or any other authorized delegate. Adjustments serve two key purposes:
- Redundancy check: Summing up the order's
baseAmountalong with the adjustment amounts will give you the final amount of the order. This formula should always be trueorder.baseAmount + order.addOns.amount + order.adjustments.amount = order.amount - Audit trail: All changes to an order are done via adjustments.
Each end point below will create an adjustment to modify the order.
Accept an Order
Accepts an order that is in a pending state. This action can only be performed by the seller or other authorized party.
If the boolean collectPayment is provided as true, this action will charge the customer's credit card that was provided during order creation. An optional message attribute can be provided with a custom message from the seller that will be included in the confirmation email that is sent.
Decline an order
Declines an order that is in a pending state
This action cannot be performed on a previously accepted order. See the cancel endpoint to cancel an already accepted order.
Add an affiliate
This end point will apply an affiliate to the given order
If affiliate is not found or if the order has a pre-applied affiliate this endpoint will throw an error. The commission and discount is calculated as per the affiliate configuration.
Add a coupon
This end point will add a coupon to the given order
If successful the API call will return an adjustment object with type coupon. However if coupon is not found or if the order has a pre-applied coupon, this endpoint will throw an error.
Change add-ons
Change the add-ons associated with the order. This end point will add or remove add-ons
If an add-on is not found in the experience, it is ignored. Add-ons are matched by name. If the price attribute is not passed, priority is given to the price defined by an existing add-on in the order. If the order does not have the add-on, the price defined in the experience is considered.
Change (Switch) Experience
Changes the experience associated with an order
Refresh your order
Since this end point makes a multitude of changes, it will return an HTTP 205 response with an empty body. You should re-fetch the entire order by making an API call to /api/orders/:id end point. This will give you an update order with all of the modifications made.
Decrease the value of an order
Decreases the value of a booking. This action is not intended to refund any payment i.e. a refund transaction will NOT be automatically created. However, if a refund=true parameter is specified, a refund will trigger if necessary.
Refund an order
Refunds a payment on an order. To cancel an order with a refund use the /cancel end point
Cancel an order
Cancels a previously accepted order and optionally offers a refund along with the cancellation. This action can only be performed by the seller or an authorized 3rd party.
Pending Orders
This action cannot be performed on a pending order. See the decline endpoint to decline a pending order.
Add guest data
Add guest data to an order which can be anything relevant to the guests participating in the experience.
Guest data can be anything relevant to the guests participating in the experience. Some sellers require information like "medical conditions", or "age" to determine whether the participants are fit for the experience. You can fetch seller questions via the /api/orders/{id}/questions endpoint.
List all seller questions
Returns a list of questions to ask the consumer after an order is place