Reserve Offer API

Use this api to easily reserve an offer. This api supports multiple use cases.

If performing multiple changes in a row on the same order lines before payment/confirmation, consistency cannot be guaranteed in case of a failure. Use with caution. It might be necessary to reset the order and start the whole process anew.

Table of Contents

  1. Add order lines to order
  2. Replace order lines in order
  3. Adding supplement products
  4. Change options
  5. Api reference

Add order lines to order

(back to Table of contents)

Add reservable offers to an order using the /v1/reserve-offers api. It accepts a set of offerIds which might need reservations, performs reservations where applicable, creates order lines from the offers, and adds them to an order. A new order is created if no orderId is supplied.

Changes to order lines has been deprecated from this api, please use the Update Order api

Special properties

selectedTravellerIds is used to specify which travellers will be included in the use of this offer. selectedTravellerIds is validated against the travellers identified in the travellerMappings property of the selected offer, as well as the legal number of user profiles per compartment when reserving a group product. Only one order line is created when reserving a group product. When reserving regular products, the number of order lines made corresponds to the number of selectedTravellerIds. Each order line will have one of the selectedTravellerIds. When selectedTravellerIds is not set, it is assumed that all travellers in the TravellerMapping should be added for the offer. selectedTravellerIds cannot be used in conjunction with count, and any attempt to do so will be rejected by the api.

Update order lines in order

(back to Table of contents)

Using this endpoint will completely override the previous version of the order line. This will also include any seat reservations. It does not support performing seat upgrades on an existing order, as the base fare product will be completely removed.

To update an order line, use the /v1/update-order api. Valid change options are accessible through the change options api.

Change options and fees are calculated compared to the last CONFIRMED version of each order line. Successive updates after replacing order lines should be done with great care. The original order line ids should then be used for best results.

Changing the number of order lines

It is possible to replace order lines by changing from a group compartment products to single person products or the inverse. In this case, the previous order line(s) will be marked as REPLACED, and new order line(s) are created. The new order line ids are returned to the client.

There are two mechanisms available to change one order line into multiple. If the order line can be replaced by a single offer, set the property selectedTravellerIds to specify which travellers are using this offer. One order line will be created for each traveller. In the case of replacing one order line with multiple offers, supply multiple offer configurations with the same order line id. Property selectedOrderLineIds must be equal.

To change from multiple order lines to one, set the property selectedOrderLineIds.

Change fees

Fees of type CHANGE may be added to the order depending on what is configured with the relevant products and their elements. In the case of a negative price difference (e.g. the new order line(s) are cheaper), a special fee of type CHANGE_NON_REFUNDABLE is added for changes concerning non-refundable products.

Adding supplement products

(back to Table of contents)

Add one or more supplement products to an order line with the endpoint /v1/update-order/supplement-products. Use the property selectedProductsConfiguration to specify selectableId and count. The provided offer must be for supplement products only, as per the Offers guide

!Note Only supplement products which does not modify the existing seat reservations may be added at this time. In practice, this is mostly Bikes and other related luggage products.

Change Options

(back to Table of contents)

A change option is a specification for a legal change that may be performed on an order. It can either be free, or come with a fee that needs to be paid. The client is responsible for selecting which changes to perform on the order.

After a change, the old tickets is no longer valid and should therefore not be accessible anymore. Remember to always redistribute and update tickets after a change. A failure to do so may lead to
  • Invalid tickets
  • Tickets with incorrect information (seats, dates etc.)
  • Misuse of tickets that have actually been cancelled

Get possible change options

The Change-options endpoint finds and returns possible change options for an order.

Changes to product or departure time

Using the update-order endpoint, it is possible to change both the product and the departure time of an order line by specifying the order line id in addition to the offer id. If the status of the order was confirmed before updating an order line, the status will be set to draft. To confirm the order, one of the following action must be performed:

  • If the new price is higher, the customer has to pay the difference.
  • If the new price is lower and the original product is refundable, the difference is credited to the customer.
  • If the new price is lower and the original product is non-refundable, a fee is added to the order line, and the order must be manually confirmed
  • If there are no price changes, the order must be manually confirmed

Change seat

To change a seat without changing product or departure time the seat map should be used. Changing seats will cancel distributed tickets and create new tickets with the correct seating information. Changing seats should only be done as the last step, as any call to /reserve-offers or /update-order will override any selected seats for the included order line(s).

When changing seats, the client must either edit the already existing reservation (recommended), or manually cancel the existing reservation and replace it with a new one. Failure to do so will lead to the train running with empty seats.

Add travellers

Adding travellers is done through Reserve-offers the same way as the initial reserving.

Remove travellers

It is possible to remove travellers in two different ways, depending on whether the order line is refundable or not. To check if an order line is refundable you can use the refund-options-endpoint in the refund-api.

  • If there are any refunding options, you can use the refund-api to perform a refund based on the refund-option that was found. Details about the refunding process is found here, and the refunding-api here.
  • If there are no refund-options, it is possible to cancel the order line manually by using the order-api. In this case a manual fee equal to 100% of the price of the cancelled order line has to be applied to the order. Use the order-api to apply fees.

After change

As an order line is one to one with a ticket-distribution-group, a change in the order line will also trigger a change in the corresponding ticket-distribution-group. When the order is completed after a change, the ticket-distributions representing the old order line will be cancelled automatically and a new one will be created based on changes.

This means that these will need to be distributed through the ticket distribution api, as if this was a regular new sale.

API reference

(back to Table of contents)

See the API reference on the Swagger Petstore