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.

Endpoint	Change 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.

🚧Backward Compatibility

Order Model Changes

Endpoint Changes

🚧
Backward Compatibility