Right of withdrawal (API3 changes)

Overview

EU Directive 2023/2673 introduces updated consumer protection requirements for distance contracts. A key change is the obligation to provide a digital withdrawal function for contracts concluded through online interfaces.

To comply, your interfaces and APIs must support a withdrawal process that meets these key requirements:

• Accessible and Always Available: The withdrawal function must be clearly visible, easy to access, and available throughout the withdrawal period.

• Two-Step Confirmation: Users must first provide or confirm their details and selected contract, then complete the withdrawal via a final confirmation action.

• Clear Labeling: The entry point and confirmation action must be explicitly and unambiguously labeled.

• Immediate Receipt: A confirmation must be sent instantly on a durable medium (e.g., email), including the withdrawal details and timestamp.

• No Manipulative Design: The process must be straightforward, with no obstacles or nudging that discourages withdrawal.

• Upfront Information: Users must be informed about the withdrawal option before entering the contract.

Suggestions for implementation

1. Update customer webs and customer apps to handle that anonymous orders needs an order key to be accessed. A suggestion would be to store the order ID and the order key in a local storage on the customer web or the customer app. It can then be retrieved even if the web page is refreshed or if the app is restarted.
   In first versions, only orders with an order key will be protected. In later versions, all orders will be protected, even if they don’t have an order key.

2. Include a message on the checkout page that informs the customer about the rights of withdrawal.

3. Add a private page that lists orders with bookings that a customer can withdraw. Allow the customer to withdraw from a payment of a booking.

4. Add a public page where a user can enter an order number and an order key. It will then list bookings that can be withdrawn. The order number and the order key are included in the order confirmation email that was sent to the user when the purchase was made.

Timeline

These changes must be in place by June 19, 2026 to ensure full compliance with the directive.

Manage withdrawals in BRP

See our documentation here on how withdrawals must be managed in BRP: Right of Withdrawal

Securing anonymous orders

An anonymous order, where no customer is specified, is (in current API3) available without any authorization. It means that anyone who knows an order ID can read the content of an anonymous order. E.g. calling  GET /api/ver3/orders/1234 .

As withdrawal from a purchase is changing the order, we need something with much higher security than we need when just reading the content of an order.

The solution that we have chosen is to add an “order key”.

Authentication for anonymous orders

When an order is created, an order key will be returned. This order key is required for all calls that read or modify the order.

The order key shall be provided in the request header  BRP-ORDER-KEY .

Affected endpoints

These endpoints will require the request header  BRP-ORDER-KEY :

• GET /api/ver3/orders

• GET /api/ver3/orders/{id}

• PUT /api/ver3/orders/{id}

• DELETE /api/ver3/orders/{id}

• POST /api/ver3/orders/{order}/items/...

• PUT /api/ver3/orders/{order}/items/...

• DELETE /api/ver3/orders/{order}/items/...

• POST /api/ver3/orders/{order}/coupons

• DELETE /api/ver3/orders/{order}/coupons/{id}

• GET /api/ver3/orders/{order}/valuecardreservations

• GET /api/ver3/orders/{order}/valuecardreservations/{id}

• POST /api/ver3/orders/{order}/valuecardreservations

• DELETE /api/ver3/orders/{order}/valuecardreservations/{id}

These endpoints will now return the property  orderKey  in the response body:

• Same endpoints as above

Example

Setting to enable

The order key is required when the setting “Temporary toggle to enable more secure anonymous orders API3” is enabled. The value of the setting is returned as requireOrderKey from the endpoints that return system settings.

List orders with bookings for withdrawal

There are two scenarios that need to be supported. Orders for a specific customer (1) or an order for an anonymous user (2).

1. Orders for a specific customer

Orders for a customer can be listed with the endpoint
GET /api/ver3/orders?customer=12 . A new query parameter is added to filter orders with bookings that are allowed to be withdrawn. Calling GET /api/ver3/orders?customer=12&forWithdrawal=true  will only return orders with bookings that are allowed to withdraw.

2. Order for an anonymous user

An order for an anonymous user can be fetched with the endpoint GET /api/ver3/orders?orderNumber=34 . A new query parameter is added to filter orders with bookings that are allowed to be withdrawn. Calling
GET /api/ver3/orders?orderNumber=34&forWithdrawal=true  will only return the order if it contains a booking that is allowed to be withdrawn.

Affected endpoints

These endpoints will support the  forWithdrawal  query parameter:

• GET /api/ver3/orders?customer=12 (with  Authorization  header)

• GET /api/ver3/orders?orderNumber=34 (with  BRP-ORDER-KEY  header)

These endpoints will no longer support anonymous calls. Will either require   Authorization  header or  BRP-ORDER-KEY  header:

• GET /api/ver3/orders?orderNumber=34

Example

Withdraw a specific booking

New endpoints have been added to withdraw from a purchase. An entire order can’t be withdrawn. Withdraw from a purchase has to be done for each booking, one by one.

New endpoints

These endpoints shall be used to withdraw from a purchase of a booking:

• POST /api/ver3/orders/{order}/items/articles/{id}/withdraw

• POST /api/ver3/orders/{order}/items/entries/{id}/withdraw

• POST /api/ver3/orders/{order}/items/events/{id}/withdraw

• POST /api/ver3/orders/{order}/items/groupactivities/{id}/withdraw

• POST /api/ver3/orders/{order}/items/services/{id}/withdraw

• POST /api/ver3/orders/{order}/items/subscriptions/{id}/withdraw

• POST /api/ver3/orders/{order}/items/valuecards/{id}/withdraw

A call to these endpoints will return  200 OK , with either success of failure. A successful response will have:

An email will be sent to the customer with information that the request have been received. The withdrawal request will be stored in the system. A back office or reception staff will have to handle the request manually. The customer will be notified when the withdrawal request have been handled.

An endpoint failure will respond with  result  set to:

• WITHDRAW_ALREADY_REQUESTED - Can’t do a second request for the same booking.

•  WITHDRAW_NOT_ALLOWED  - The booking was not withdrawn. It’s not allowed to withdraw this booking.

•  UNKNOWN_FAILURE  - The booking was not withdrawn. Something failed. You should inform the customer to contact the facility for help.

Item bookings

A physical product (item) might already have been picked up from the reception.  The purchase should not be refunded before the product has been returned. We therefore return two different result codes.

The returned  result  property can have the following codes:

•  WITHDRAW_REQUEST_CREATED  - The product hasn’t been picked up and therefore a withdrawal request have been created.

•  WITHDRAW_REQUEST_CREATED_RETURN_ARTICLE  - The product has already been picked up. Inform the user to return the product to the reception. A withdrawal request have been created but it will not be handled until the user has returned the product.

Messages

This message will be available from the endpoint  GET /api/ver3/messages/rightOfWithdrawal . 

Settings

• The setting “Right of withdrawal from online purchase” enables this feature. The setting is returned as enableRightOfWithdrawalFromPurchase from the endpoints that return full business unit objects.

• To enable “Securing anonymous orders”. See Right of withdrawal (API3 changes)

Contact

If you have any questions or need support during the integration process, please don’t hesitate to reach out to our support team.

Changelog