Overview

Marketplace provides 2 ways to work with orders:

  • create/update whole order with orderItems
  • add/update/delete single orderItems to/from the existing order

On the client-side, the full order object is created with references to products and travelers. You can find the base URLs here.

POST https://api.discover.swiss/market/v1/orders
PUT https://api.discover.swiss/market/v1/{orderNumber}
DELETE https://api.discover.swiss/market/v1/{orderNumber}

Order model defintion: see here

Example ordering Zürich-card

This sample order contains two orderItem, Zürich-card24 and Zürich-card72. It shows the minimal data that the client must send to create an order.

Sample order:

{
  "orderStatus": "Placed",
  "priceCurrency": "CHF",
  "Customer": {
    "givenName": "John",
    "familyName": "Dou",
    "birthDate": "1974-12-18T00:00:00Z",
    "email": "j.dou@test.biz"
  },
  "orderedItem": [
      {
          "orderQuantity": 1,
          "orderedItem": {
              "product": {
                    "identifier": "NOVA_zurichcard24"
              },
              "validFrom": "2019-12-24T06:15:00+01:00",
              "traveler": [
                  {
                      "givenName": "Philipp",
                      "familyName": "Muster",
                      "birthDate": "1968-06-26T00:00:00+02:00"
                  }
              ]
          }
      },
      {
          "orderQuantity": 1,
          "orderedItem": {
              "product": {
                    "identifier": "NOVA_zurichcard72"
              },
              "validFrom": "2019-12-28T06:15:00+01:00",
              "traveler": [
                  {
                      "givenName": "Sohn",
                      "familyName": "Tester",
                      "birthDate": "2008-01-01T00:00:00+01:00"
                  }
              ]
          }
      }
  ],
  "term": [
      {
          "termCode": "ZHT-AGB|ZHT-DPP",
          "accepted": true
      }
  ]
}

!!! Warning "Locking of the order" (prevent concurrency violation)

The order is locked for the duration of each request execution or until 5 minutes are up.
Locking means that only one request can modify the order at the same time, and all other requests will receive 423 error.

Additional info:

  • The customer data is taken from the profile-person object
  • A BillingAddress is not mandatory, because we create e-tickets only
  • The product Identifier is the same in all environments (test/prod) but prices can change
  • The order validation will add the name and the price to the orderItem
  • ValidFrom is the desired starting date and time of the ticket
  • orderNumber and orderItemNumber are determined by the server and not part of the request
  • orderItemStatus is determined by the server and not part of the request

Note

For public transportation tickets, the ValidFrom date should be less than 2 months in the future.