Skip to content

OfferBundles and offers

What is offerBundle and offer

In general, offers deliver all information a guest needs to make a decision to actually buy the product with certain options and given times. There can be several offer-bundles in the response and the guest always chooses a full bundle (not a single offer). A bundle will always cover the full group and make sure they stay together (for example the same route or same rafting trip).

An Offerbundle contains a list of offers for each traveler and the total price information about it.

An Offer contains all information from the provider's system about the product for traveler. Model defintion for Offerbundle and Offer : see here

Where to use offerBundle

OfferBundle can be used for:

How to work with offerBundle

Get the offerBundle

First of all it is necessary to get offers

To get offers there are 2 ways:

  • find offerBundle manually
  • provide product configuration with orderItem create/update request, then offerBundle will be searhced automatically.

Get offerBundle with find offer endpoint

Info

You do not have to provide the givenName and familyName. However, if you decide to use this offerBundle, then required information must be provided later or at this stage.

POST https://api.discover.swiss/test/b2bmarket/v1/orders/{orderNumber}/offers
{
    "product": {
        "identifier": "nova_zurichcard72"
    },
    "validFrom": "2021-10-15T00:00:00",
    "traveler": [
        {
            "identifier": "jhon",
            "birthDate": "1980-02-18",
            "givenName": "Jhon",
            "familyName": "Smith"
        },
        {
            "identifier": "jessika",
            "birthDate": "1979-02-18T15:00:00"
        }
    ]
}
POST https://api.discover.swiss/test/b2bmarket/v1/orders/{orderId}/offers
{
    "validationMessages": [],
    "offerBundle": [
        {
            "id": "9293c9dc-2180-4e6d-bc73-bfb3db8e6da1",
            "totalPrice": 10600,
            "currency": "CHF",
            "expiresAt": "2021-10-12T12:39:32+00:00",
            "offer": [
                {
                    "id": "3ea728a2-6d55-4676-a74a-0ceec5f27eb9",
                    "expiresAt": "2021-10-12T12:39:32+00:00",
                    "title": "ZVV Zürich Card 72 hours",
                    "description": ".\tA ticket for visitors and guests who would like to combine their stay with a visit to a museum or an excursion to the local recreation area, also valid for travel between the airport and the city.\n\n.\tZones 110 111 121 140 150 154 155.\n\n.\tPeriod of validity: 72 hours.\n\n.\tAvailable for 2nd class travel.\n\n.\tReduced fare for children from their 6th to their 16th birthday.\n\n.\twww.zuerichcard.com",
                    "travelerId": "jessika",
                    "price": 5300,
                    "currency": "CHF"
                },
                {
                    "id": "db05d275-2e4c-4365-a987-4c397b66e065",
                    "expiresAt": "2021-10-12T12:39:32+00:00",
                    "title": "ZVV Zürich Card 72 hours",
                    "description": ".\tA ticket for visitors and guests who would like to combine their stay with a visit to a museum or an excursion to the local recreation area, also valid for travel between the airport and the city.\n\n.\tZones 110 111 121 140 150 154 155.\n\n.\tPeriod of validity: 72 hours.\n\n.\tAvailable for 2nd class travel.\n\n.\tReduced fare for children from their 6th to their 16th birthday.\n\n.\twww.zuerichcard.com",
                    "travelerId": "jhon",
                    "price": 5300,
                    "currency": "CHF"
                }
            ]
        }
    ]
}

Get offerBundle with placement of the orderItem

It is possible to get offerBundle during the creation of the orderItem. For that it is necessary to declare full product configuration in the orderItem defintion withour providing of offerBundleId.

{
    "orderQuantity": 1,
    "orderedItem": {
        "product": {
            "identifier": "nova_zurichcard72"
        },
        "validFrom": "2021-10-15T00:00:00",
        "traveler": [
            {
                "identifier": "jhon",
                "birthDate": "1980-02-18",
                "givenName": "Jhon",
                "familyName": "Smith",
                "salutation": "Mr"
            },
            {
                "identifier": "jessika",
                "birthDate": "1979-02-18T15:00:00",
                "givenName": "Jessika",
                "familyName": "Smith",
                "salutation": "Mrs"
            }
        ]
    }
}
POST https://api.discover.swiss/test/b2bmarket/v1/orders/{orderId}/items
{
    "orderItem": {
        "orderItemNumber": "21-102000-1",
        "orderItemStatus": "Placed",
        "orderQuantity": 1,
        "orderedItem": {
            "product": {
                "identifier": "nova_zurichcard72",
                "productIdentifier": "nova_zurichcard",
                "sku": "898",
                "name": "ZVV Zürich Card, ZVV Zürich Card 72 hours",
                "dataGovernance": {
                    "provider": {
                        "acronym": "sbb"
                    },
                    "term": {
                        "code": "ZHT-AGB|ZHT-DPP"
                    },
                    "source": {
                        "acronym": "zht"
                    }
                },
                "priceList": [
                    {
                        "priceCHF": 37.0,
                        "maxAllowedAge": 15,
                        "minAllowedAge": 5
                    },
                    {
                        "priceCHF": 53.0,
                        "maxAllowedAge": 2500,
                        "minAllowedAge": 15
                    }
                ],
                "taxRate": 0.077
            },
            "validFrom": "2021-10-15T00:00:00+00:00",
            "traveler": [
                {
                    "priceCHF": 53.0,
                    "identifier": "jhon",
                    "salutation": "Mr",
                    "givenName": "Jhon",
                    "familyName": "Smith",
                    "birthDate": "1980-02-18T00:00:00"
                },
                {
                    "priceCHF": 53.0,
                    "identifier": "jessika",
                    "salutation": "Mrs",
                    "givenName": "Jessika",
                    "familyName": "Smith",
                    "birthDate": "1979-02-18T00:00:00"
                }
            ]
        },
        "orderDelivery": "e-ticket",
        "amount": 106.0,
        "amountCHF": 106.0,
        "taxRate": 8.161999999999999,
        "taxCHF": 8.161999999999999,
        "ticket": [],
        "offerBundleId": "2ecd1d56-e058-425d-8847-4190c10ebd11"
    },
    "validationMessages": [],
    "itemOffer": []
}

How to apply offerBundle

Once you have an offerBundle, you can use its offerBundleId to create/update a new orderItem.

Tip

OfferBundleId can be used in only one orderItem.

Information

It is necessary to provide only required properties for travelers fields and then there is still a possibility to update travelers during adding/updating of OI.
To do so, you must provide the same travelers identifiers that sent in the request to get the offer or offerBundle and attached with the offerBundleId in orderItem. Read more

{
    "orderQuantity": 1,
    "offerBundleId":"9293c9dc-2180-4e6d-bc73-bfb3db8e6da1",
    "orderedItem": {
        "traveler": [
            {
                "identifier": "jhon",
                "birthDate": "1980-02-18",
                "givenName": "Jhon",
                "familyName": "Smith",
                "salutation": "Mr"
            },
            {
                "identifier": "jessika",
                "birthDate": "1979-02-18T15:00:00",
                "givenName": "Jessika",
                "familyName": "Smith",
                "salutation": "Mrs"
            }
        ]
    }
}
POST https://api.discover.swiss/test/b2bmarket/v1/orders/{orderId}/items
{
    "orderItem": {
        "orderItemNumber": "21-102000-2",
        "orderItemStatus": "Placed",
        "orderQuantity": 1,
        "orderedItem": {
            "product": {
                "identifier": "nova_zurichcard72",
                "productIdentifier": "nova_zurichcard",
                "sku": "898",
                "name": "ZVV Zürich Card, ZVV Zürich Card 72 hours",
                "dataGovernance": {
                    "provider": {
                        "acronym": "sbb"
                    },
                    "term": {
                        "code": "ZHT-AGB|ZHT-DPP"
                    },
                    "source": {
                        "acronym": "zht"
                    }
                },
                "priceList": [
                    {
                        "priceCHF": 37.0,
                        "maxAllowedAge": 15,
                        "minAllowedAge": 5
                    },
                    {
                        "priceCHF": 53.0,
                        "maxAllowedAge": 2500,
                        "minAllowedAge": 15
                    }
                ],
                "taxRate": 0.077
            },
            "validFrom": "2021-10-15T00:00:00+00:00",
            "traveler": [
                {
                    "priceCHF": 53.0,
                    "identifier": "jhon",
                    "givenName": "Jhon",
                    "familyName": "Smith",
                    "birthDate": "1980-02-18T00:00:00"
                },
                {
                    "priceCHF": 53.0,
                    "identifier": "jessika",
                    "birthDate": "1979-02-18T00:00:00"
                }
            ]
        },
        "orderDelivery": "e-ticket",
        "amount": 106.0,
        "amountCHF": 106.0,
        "taxRate": 8.161999999999999,
        "taxCHF": 8.161999999999999,
        "ticket": [],
        "offerBundleId": "9293c9dc-2180-4e6d-bc73-bfb3db8e6da1"
    },
    "validationMessages": [],
    "itemOffer": []
}

Single offerBundle

When adding orderItem there is only one offerBundle, then this offerBundle will be selected automatically.

Multiple offer bundles

When adding orderItem there are several offerBundle, then they will be returned in the response together with order/orderItem. The orderItem will be in Checkout status until the selection of offerBundleId.

Warning

Currently, it is not possible to get several offerBundles

Here is an example of how order's response looks when the multiple offerBundles returned

{
  "Order": {
    "OrderNumber": "1",
    "OrderDate": "2021-07-02T00:00:00+00:00",
    "Customer": {
      "ProfileId": "valid",
      "AdditionalName": "",
      "Address": {
        "AddressCountry": "CH",
        "AddressLocality": "Buchs",
        "AddressRegion": "St. Gallen",
        "PostalCode": "9470",
        "StreetAddress": "Heldaustrasse 43"
      },
      "Email": "testmail@test.ch",
      "FamilyName": "Hermes",
      "FaxNumber": "0123456789",
      "Gender": "Male",
      "GivenName": "Marianne",
      "Nationality": "Swiss",
      "BirthDate": "1978-01-01",
      "Telephone": "0123456789",
      "IsGuest": "True",
      "CreatedDateTime": "2019-09-18T02:00:00-06:00",
      "LastModified": "2019-09-18T04:00:00-06:00"
    },
    "OrderStatus": "Checkout",
    "PriceCurrency": "CHF",
    "TotalAmount": 0.0,
    "TotalAmountCHF": 0.0,
    "TotalTaxCHF": 0.0,
    "Language": "de",
    "OrderedItem": [
      {
        "OrderItemNumber": "1-1",
        "OrderItemStatus": "Checkout",
        "OrderQuantity": 1,
        "OrderedItem": {
          "Product": {
            "Identifier": "some_multiple_offer_product",
            "ProductIdentifier": "some_offer_product",
            "@product": "{{ infoUrl }}/products/some_offer_product",
            "Sku": "102",
            "Name": "Sbb product with multiple offers",
            "DataGovernance": {
              "Provider": {
                "Acronym": "SBB"
              },
              "Term": {
                "Code": "ZHT-AGB"
              },
              "Source": {
                "Acronym": "ZHT"
              }
            },
            "PriceList": [
              {
                "PriceCHF": 19,
                "MinAllowedAge": 5,
                "MaxAllowedAge": 15
              },
              {
                "PriceCHF": 27,
                "MinAllowedAge": 15,
                "MaxAllowedAge": 2500
              }
            ],
            "TaxRate": 0.0
          },
          "ValidFrom": "2021-05-06T00:00:00", 
          "Traveler": [
            {
              "Identifier": "paxa",
              "Salutation": "Mr",
              "GivenName": "James",
              "FamilyName": "Bond",
              "BirthDate": "1990-02-18T00:00:00"
            }
          ]
        },
        "OrderDelivery": "e-ticket",
        "Amount": 0.0,
        "AmountCHF": 0.0,
        "TaxRate": 0.0,
        "TaxCHF": 0.0,
        "Ticket": []
      }
    ],
    "Term": [],
    "PartnerAcronym": "someAcronym",
    "ProfileId": "valid",
    "@id": "https://api.discover.swiss/test/b2bmarket/v1/orders/21-102000",
    "CreatedDateTime": "2021-07-01T18:00:00-06:00", 
    "LastModified": "2021-07-01T18:00:00-06:00" 
  },
  "ValidationMessages": [
    {
      "Level": "Warning",
      "Message": "Wählen Sie ein Angebot für die Bestellposition 1-1",
      "OrderItemNumber": "1-1"
    }
  ],
  "ItemOffer": [
    {
      "productConfiguration": {
        "product": {
          "identifier": "some_multiple_offer_product",
          "productIdentifier": "some_offer_product",
          "@product": "{{ infoUrl }}/products/some_offer_product",
          "sku": "777",
          "name": "Sbb product with multiple offers",
          "dataGovernance": {
            "provider": {
              "acronym": "SBB"
            },
            "term": {
              "code": "ZHT-AGB"
            },
            "source": {
              "acronym": "ZHT"
            }
          },
          "priceList": [
            {
              "priceCHF": 19,
              "minAllowedAge": 5,
              "maxAllowedAge": 15
            },
            {
              "priceCHF": 27,
              "minAllowedAge": 15,
              "maxAllowedAge": 2500
            }
          ],
          "taxRate": 0.0
        },
        "validFrom": "2021-09-06T00:00:00",
        "traveler": [
          {
            "PriceCHF": 27.0,
            "salutation": "Mr",
            "identifier": "paxa",
            "givenName": "James",
            "familyName": "Bond",
            "birthDate": "1990-02-18T00:00:00"
          }
        ]
      },
      "orderItemNUmber": "1-1",
      "offerBundle": [
        {
          "id": "96d78195-49d7-43ad-89c9-619e49e474dc",
          "totalPrice": 2700,
          "currency": "CHF",
          "expiresAt": "2021-08-11T18:18:49", 
          "offer": [
            {
              "id": "088ffebd-bbc7-43bd-a9b9-4731bfd57e75", 
              "expiresAt": "2021-08-11T18:18:49",
              "title": "Product which provide multiple offers",
              "description": ".\tProduct with alternatives",
              "travelerId": "paxa",
              "price": 2700,
              "currency": "CHF"
            }
          ]
        },
        {
          "id": "9f23ce05-552c-4e40-8222-cd1cc6421bcc",
          "totalPrice": 2800,
          "currency": "CHF",
          "expiresAt": "2021-08-11T18:18:49", 
          "offer": [
            {
              "id": "180c5048-bd18-48fd-8891-6afbea58f3cd", 
              "expiresAt": "2021-08-11T18:18:49",
              "title": "Product which provide multiple offers",
              "description": ".\tProduct with alternatives",
              "travelerId": "paxa",
              "price": 2800,
              "currency": "CHF"
            }
          ]
        }
      ]
    }
  ]
}

Offer's time limit "Expiration"

Each offerBundle and offer contains expiredAt property which indicates the expiration time of the offer. If any of the offers inside of the offerBundle expires, then offerBundle is also expired.

When the offer bundle/offer expired, it is not possible to continue work with that orderedItem. See: updating of an order or updating an orderItem

Information

If offerBundle had expired before order is paid, then it is necessary to replace expired orderItem with new set offerBundleId or remove this orderItem.

Warning

If offerBundle expires after the order has been paid, then the order's status will be changed to fulfillment error and the money for this orderItem will be refunded.


Last update: December 2, 2021 16:32:19