HomeGuidesRecipesAPI ReferenceChangelog
GuidesAPI ReferenceCustomer Help CenterLog In
Changelog

v2017-09-28: Packages

This version introduces a significant change to the order data structure. An order can now contain multiple items -- each item representing a different experience. This allows for a customer to purchase multiple experiences and bundle them all into a single order.

The ability to create ad-hoc multi-item orders will be introduced in a later version.

In this version, we introduce the concept of Packages. A package is pre-bundled collection of experiences. It also allows you to offer package discounts to incentivize your customers to purchase these bundles.

🚧

Backward Compatibility

For integrations using an older API version, all operations made using the older API version will always affect the first item in an order. To operate on orders with more than one item, you must upgrade your API version.

Order Model Changes

Here is a comparison of the new vs. old version of an Order model with a single item.

{
  "id": "ORDER_ID",
  "amount": 19.99, // total across all items
  "balance": 0,
  "adjustments": [...], // only payment adjustments (does not affect amount)
  "customerName": "John Doe",
  "customerEmail": "[email protected]",
  "seller": {
    "id": "SELLER_ID"
  },
  "items": [
    {
      "experience": {
        "id": "EXPERIENCE_ID"
      },
      "event": {
        "id": "EVENT_ID"
      },
      "arrival": "2017-09-28",
      "arrivalTime": 1015,
      "status": 200,
      "guestStatus": "pending",
      "quantity": 1,
      "currency": "USD",
      "price": 19.99,
      "priceType": "person",
      "name": "Experience name",
      "shortCode": "ABC123",
      "adjustments": [...], // non-payment adjustments (affects order amount)
      "demographics": [...],
      "addOns": [...],
      "guests": [...],
      "guestsData": [...],
      "group": {...},
      "groupDiscount": {...}
    }
  ],
}
{
  "id": "ORDER_ID",
  "amount": 19.99,
  "balance": 0,
  "customerName": "John Doe",
  "customerEmail": "[email protected]",
  "seller": {
    "id": "SELLER_ID"
  },
  "experience": {
    "id": "EXPERIENCE_ID"
  },
  "event": {
    "id": "EVENT_ID"
  },
  "arrival": "2017-09-28",
  "arrivalTime": 1015,
  "status": 200,
  "guestStatus": "pending",
  "quantity": 1,
  "currency": "USD",
  "price": 19.99,
  "priceType": "person",
  "name": "Experience name",
  "shortCode": "ABC123",
  "adjustments": [...],
  "demographics": [...],
  "addOns": [...],
  "guests": [...],
  "guestsData": [...],
  "group": {...},
  "groupDiscount": {...}
}

Here is a comparison of the new vs. old version of and Order model with a package (multiple items). The backported version is not meant to be fully functional nor will it provide a completely accurate representation of the package since significant portions of the order will be missing (i.e. all items beyond the first one). It merely serves to ensure nothing significant breaks with your integration.

The key differences to notice are:

  • Only the first item is retained in the backported version.
  • In the new version, payment-related adjustments are in the root of the order whereas non-payment adjustments (discounts, modifications, etc) are within the items. In the old version, all adjustments are at the root of the order.
  • In the new version, the status has moved to the item level since each item in an order may have different statuses.
{
  "object": "order",
  "id": "****4d16",
  "amount": 92,
  "balance": 0,
  "customerName": "Pegasus Melvin",
  "customerEmail": "[email protected]",
  "traveler": {
    "id": "****4d11"
  },
  "source": "checkout",
  "adjustments": [
    {
      "id": "****4d14",
      "type": "payment_request",
      "amount": -92,
      "payment": {
        "method": "cc",
        "card": "****4d1c"
      }
    },
    {
      "id": "****4d1f",
      "type": "payment",
      "amount": -92,
      "payment": {
        "method": "cc",
        "card": "****4d1c"
      }
    }
  ],
  "tags": [...],
  "conversation": {
    "id": "****4d15"
  },
  "seller": {
    "id": "****4571"
  },
  "package": {...},
  "items": [
    {
      "object": "experience_item",
      "id": "****4cfa",
      "name": "Lighthouse Lovers Cruise",
      "event": {
        "id": "****7804"
      },
      "experience": {
        "id": "****458e"
      },
      "arrival": "2019-07-19",
      "arrivalTime": 1330,
      "quantity": 2,
      "amount": 38.64,
      "status": 200,
      "demographics": [...],
      "adjustments": [
        {
          "id": "****4d12",
          "type": "package_discount",
          "amount": -3.36,
          "itemId": "****4cfa"
        }
      ],
      "guestsData": [...],
      "guests": [...],
      "price": 21,
      "priceType": "person"
    },
    {
      "object": "experience_item",
      "id": "****4d03",
      "name": "City Tour",
      "seller": {
        "id": "****4571"
      },
      "event": {
        "id": "****7835"
      },
      "experience": {
        "id": "****458c"
      },
      "arrival": "2019-07-19",
      "arrivalTime": 915,
      "quantity": 2,
      "amount": 53.36,
      "status": 200,
      "guestStatus": "pending",
      "demographics": [...],
      "adjustments": [
        {
          "id": "****4d13",
          "type": "package_discount",
          "amount": -4.64,
          "itemId": "****4d03"
        }
      ],
      "guestsData": [...],
      "guests": [...],
      "price": 29,
      "priceType": "person"
    }
  ]
}
{
  "object": "order",
  "type": "order",
  "id": "****4d16",
  "amount": 92,
  "balance": 0,
  "customerName": "Pegasus Melvin",
  "customerEmail": "[email protected]",
  "traveler": {
    "id": "****4d11"
  },
  "source": "checkout",
  "adjustments": [
    {
      "id": "****4d14",
      "type": "payment_request",
      "amount": -92,
      "payment": {
        "method": "cc",
        "card": "****4d1c"
      }
    },
    {
      "id": "****4d1f",
      "type": "payment",
      "amount": -92,
      "payment": {
        "method": "cc",
        "card": "****4d1c"
      }
    },
    {
      "id": "****4d12",
      "type": "package_discount",
      "amount": -3.36,
      "itemId": "****4cfa"
    }
  ],
  "tags": [...],
  "conversation": {
    "id": "****4d15"
  },
  "seller": {
    "id": "****4571"
  },
  "package": {...},
  "experience": {
    "id": "****458e"
  },
  "status": 200,
  "quantity": 2,
  "guestStatus": "pending",
  "experienceName": "Lighthouse Lovers Cruise",
  "price": 21,
  "priceType": "person",
  "arrival": "2019-07-19",
  "arrivalTime": 1330,
  "demographics": [...],
  "event": {
    "id": "****7804"
  },
  "guests": [...],
  "guestsData": [...]
}

Endpoint Changes

The following endpoints have been modified in this version.

EndpointChange Summary
POST /api/orders
POST /api/orders/prepare
GET /api/orders
GET /api/orders/{id}
GET /api/transactions
GET /api/transactions/{id}
Several root level properties have moved into the items object.
POST /api/orders/{id}/increase
POST /api/orders/{id}/decrease
POST /api/orders/{id}/arrival
POST /api/orders/{id}/changeQuantity
POST /api/orders/{id}/changeAddOns
POST /api/orders/{id}/checkInGuests
All root level properties have moved into the items object.
POST /api/forms
GET /api/forms
GET /api/forms/{id}
GET /api/orders/{id}/questions
The experience property has been renamed to product. The product may be an experience or a package.