Calculations API

There are many variables that determine the total price of an order. The calculations API will help solve these problems for you by validating and calculating various prices and amounts for you.

The following calculations are supported:

Demographic pricing
Group discount
All types of coupon discounts (except unlock)
Gift codes and Store Credits
Affiliate discounts and deposits
Add-ons
Ad-hoc custom charges
Package discounts
Taxes and Fees
Partner Fees

The Prepare API Endpoint

The calculations API has been baked into the Prepare an order API call to support a new line item based payload.

Here is the format of the payload accepted by the /api/orders/prepare endpoint.

{
  "customerName": "John Doe",
  "customerEmail": "[email protected]", // Optional
  // Each 'item' represents one experience that is being booked.
  "items": [
    {
      "experience": {
        "id": "57b7395ce0179850233b43ad"
      },
      "arrival": "2020-05-2",
      "arrivalTime": 1625, // Optional as per booking requirement
      
      // Each line item below will reference one specific line item in your
      // order. Supported line items are documented bellow
      "lineItems": [
        {
          "object": "<object-key>",
          "key": "value pair of variables"
        },
        {
          "object": "<object-key>",
          "code": "something"
        }
        // As many as possible
      ]
    }
  ]
}

Each item in the lineItems attribute represents a unique line item in an order's summary. The item (demographics, coupons, add-ons etc) should contain basic information required to calculate the price and amount of your required entity. There can be multiple line items representing each row in your payment summary -- for example for two demographics (Adults, Children) there should be two lineitem_demographic entries.

The supported line items are documented below. Every attribute in the line item is required unless explicitly commented as optional.

{
  "object": "lineitem_demographic",
  "demographic": {
    "id": "57b7395ce0179850238b45ae" // The demographic ID from /api/experiences/{id}
  },
  "quantity": 1 // Optional - Defaults to 1 if not specified
}

Any configured group discount will automatically be applied based on the quantities specified in all the lineitem_demographic line items.

{
  "object": "lineitem_coupon",
  "code": "my-coupon-code"
},

{
	"object": "lineitem_affiliate",
	"code": "hilton-front-desk",
	"amount": 10 // An optional deposit amount that was given as payment to the affiliatee
}

If you do know what type of code the user has supplied (Coupon, Affiliate, Gift, Store Credit), then use the generic lineitem_code object

{
  "object": "lineitem_code",
  "code": "some-code" // Any kind of code if you don't know what type it is
}

{
  "object": "lineitem_addon",
  "addOn": {
    "id": "addOn-id" // Get this from /api/experiences/{id}
  },
  "quantity": 1 // Optional - defaults to 1 if not specified
}

Custom charges can be specified during booking creation time, they require several parameters.

{
  "object": "lineitem_custom_charge",
  "name":  "The name of my custom charge",
  "price": 103,
  "quantity": 1, // Optional - defaults to 1 if not specified
  "hasFees": false // Defaults to false. Set to true to have pre-configured taxes applied
}

The taxes and fees configured in a particular seller's account will automatically be applied for you without them being specified. However certain scenarios require the user to exclude certain taxes in fees. In such situations you should only specify the fee that needs to be excluded using the following line item

{
  "object": "lineitem_fee",
  "id": "fee-id",
  "excluded": true
}

Sample request

Here is an exhaustive sample request that can be sent to the prepare endpoint. Please ensure you have set any required X-API-KEY and X-API-VERSION headers to your request

{
  "customerName": "Jane Doe",
  "customerEmail": "[email protected]",
  "package": {"id": "5e969af47a84dcc4ff6a3d07"}, // Only required if you are booking a package
  "items": [
    {
      "experience": {
        "id": "57b7395ce0279950238b45af"
      },
      "arrival": "2020-04-13",
      "arrivalTime": 1625, // Optional based on experience configuration
      "lineItems": [
        {
          "object": "lineitem_demographic",
          "demographic": {
            "id": "57b7395ce0079820438b45ae"
          },
          "quantity": 3
        },
        {
          "object": "lineitem_demographic",
          "demographic": {
            "id": "57b739b2926205f4548b359c"
          }
        },
        {
          "object": "lineitem_coupon",
          "code": "my-coupon-code"
        },
        {
          "object": "lineitem_affiliate",
          "code": "hilton-hotel",
          "amount": 10
        },
        {
          "object": "lineitem_code",
          "code": "my-gift-code"
        },
        {
          "object": "lineitem_addon",
          "addOn": {
            "id": "57b742a16864ea90138b4715"
          },
          "quantity": 2
        },
        {
          "object": "lineitem_custom_charge",
          "name": "Pepsi",
          "price": 1.5,
          "quantity": 2,
          "hasFees": true
        },
        {
          "object": "lineitem_fee",
          "id": "fee-id",
          "excluded": true
        }
      ]
    }
  ]
}

API Response

The response from the /api/orders/prepare endpoint is a JSON payload that can be sent to the Create a new Order endpoint. It contains all the information required by the order API.

Additionally, the prepare endpoint returns two additional attributes within each item that will give you information that can be displayed to the end user.

The breakdown key in each item will have a string version of the payment summary that can be easily shown to the end user.
The lineItems key in each item will be returned enhanced by additional information from the API. For example, if you specified a demographic id we will return to you the final price for that demographic including any discounts. We will also return detailed meta information for a coupon, affiliate etc.

Error Handling

The /api/orders/prepare endpoint will perform a lot of validation, and return errors wherever possible. Examples of validation are:

Verify if a supplied coupon code is valid or not.
Verified if a supplied demographic or add-on ID is present and configured within a listing

Any missing demographic information will be handled by returning an HTTP 4xx error code. However other errors will be returned as a part of the lineItems attribute within the response itself. Please see sample request and response payloads below for an example

Sample Response

The full response from the /api/orders/prepare end point is too large to show here. Here are a few snippets from a typical response to indicate what a typical breakdown and lineItems payload in the response would look like.

Breakdown

{
  "items": [
    {
      "demographics": [
        // Some demographics here
      ],
      
      // The breakdown gives an easier to read and display set of strings 
      // to show to your end user
      "breakdown": [
        {
          "Adults 18+ ($15.00 × 3)": "$45.00"
        },
        {
          "Youth 10-17 ($7.00 × 1)": "$7.00"
        },
        {
          "Add-Ons": "$6.00"
        },
        {
          "Pepsi × 2": "$3.00"
        },
        {
          "Total": "$61.00"
        }
      ]
    }
  ]
}

Line Items

The items key of the response will contain the entire lineItems payload that you sent to Xola. It will be enhanced with:

Additional information regarding successful line items - for example: Coupon & Add-on details
Any error messages for invalid line items.

Here is an example of the lineItems key from the response:

{
  "items": [{
    "demographics": [
      // Some demographics here
    ],
    "lineItems": [
      {
        "object": "lineitem_demographic",
        "demographic": {
          "id": "57b7395ce0179850238b45ae"
        },
        "quantity": 3,
        "price": 15,
        "amount": 45
      },
      {
        "object": "lineitem_demographic",
        "demographic": {
          "id": "57b739b2926705f4548b458c"
        },
        "quantity": 1,
        "price": 7,
        "amount": 7
      },
      {
        "object": "lineitem_coupon",
        "code": "my-coupon-code",
        "errors": {
          "items.coupon": {
            "reason": "invalid_coupon",
            "message": "Code not found"
          }
        }
      },
      {
        "object": "lineitem_code",
        "code": "my-gift-code",
        "errors": {
          "reason": "invalid_code",
          "message": "Code 'my-gift-code' not found"
        }
      },
      {
        "object": "lineitem_addon",
        "addOn": {
          "id": "57b742a16864ea91138b4675"
        },
        "quantity": 2,
        "price": 6,
        "amount": 12,
        "configuration": {
          "name": "Rain Poncho",
          "price": 6,
          "visibility": "public",
          "object": "quantity",
          "desc": "Some description"
        }
      },
      {
        "object": "lineitem_custom_charge",
        "name": "Pepsi",
        "price": 1.5,
        "quantity": 2,
        "hasFees": true,
        "amount": 3,
        "configuration": {
          "name": "Pepsi",
          "price": 1.5,
          "visibility": "custom",
          "id": "5e96c3b47a84dc295632be2c"
        }
      }
    ]
  }]
}