search

openactive / open-booking-api

Repository for the Open Booking API specification
Other
2 stars 3 forks source link

Clarify Orders feed "PATCH" #126

Open nickevansuk opened 4 years ago

nickevansuk commented 4 years ago

Proposer

ODI

Why is this needed?

The current specification includes high level guidance that "the properties included in the Orders feed may be a subset of the Order response from B (effectively making the Orders feed a series of PATCH requests for the Broker)"

Although this is descriptive, and what this means in practice can be inferred from other parts of the specification, it is open to creating confusion and allows for a broad interpretation if not read in the context of the whole specification. This creates additional complexity for Brokers, who would need to deal with a wide variety of different interpretations, without providing additional value to Booking Systems, who would prefer to have a concrete set of requirements to work from.

Additionally both this specification and the Modelling Opportunity Data specification on which this specification is based do not allow for explicit null values to exist within the model, which impedes property removal, and hinders any straightforward implementation of a granular PATCH.

Picking up on a specific complexity of the feed: the purpose of including the orderedItem, acceptedOffer and unitTaxSpecification in the Orders Feed was to allow them to be updated, however such an update was not well defined. Such an update can be labelled ("OrderItem Replacement"), clarified, and made clearly optional for the Booking System - such that these properties only need to be included in the Orders feed when they can be updated - which will further simplify implementation.

This proposal recommends additional clarity be added to the specification to make processing the Orders Feed more straightforward, and to help improve the quality of validation and tooling that can be created. It also makes any notifications expected to be produced from changes to the feed explicit to aid the Booking System and Broker in their implementations.

Note this proposal does not include any functional changes to the feed, and the Orders Feed examples used in the current specification will conform to the clarified wording as-is.

Proposal

Broker: Processing the Orders feed

The Broker MUST maintain an up-to-date store of Orders and OrderProposals received from the Booking System. Each Order or OrderProposal received is compared to the last version stored by the Broker, and any differences between the old and new content can trigger notifications and refunds to the Customer, as well as updating the Broker's store.

Hence it is important for the Broker to consider their store of Orders and OrderProposals as durable, and not simply a cache, to ensure their Customers always get relevant notifications.

The Order/OrderProposal properties included in the Orders feed MUST be a subset of the Order/OrderProposal properties returned in the response from B or P as specified below (effectively making the Orders feed a series of partial update requests for the Broker). It is the responsibility of the Broker to process the contents of the Orders feed in a manner that maintains a complete view of the Order state.

The following properties of the Order or OrderProposal MUST be included in the Orders feed, and the Broker MUST overwrite its previous copy of each property when processed:

Additionally, the orderedItem property of the Order or OrderProposal MUST be included in the Orders feed. Noting the exceptions outlined in this section, all other properties of the OrderItems MUST overwrite the Broker's previous copy of each when processed, and if a property is no longer present the Broker must remove it. This includes the following properties, and any additional supported extensions:

For OrderItem in both Order and OrderProposal:

And for OrderItem in OrderProposal it additionally includes:

As an exception to the above for Orders, if the orderedItem property is not present in the OrderItems in the Orders feed (in the case that the Booking System does not support Replacement), the following properties are assumed to be immutable for that Order, and the Broker MUST NOT overwrite their previous copy of each (taken at B) when processing the Orders feed:

The following properties MUST always be included in the Orders feed for the convenience of the Broker, and MUST be immutable:

Additionally any properties within objects included in the properties above that were included in the original response from B or P MUST be included in the Orders feed, with the exception of the following.

The following properties MUST NOT be included in the Orders feed and MUST always be maintained by the Broker and not overwritten; hence changes to these properties MUST NOT be permitted after B:

Properties in Order and OrderProposal:

Properties in OrderItem within Order only:

Opportunity Data updates for Orders MUST NOT be read from the Orders feed, and must instead be updated using the Opportunity Data [[RPDE]] open feeds as specified in Change of logistics notification.

Brokers reading OrderItems in OrderProposals, or Replacements, from the Orders feed MUST look up the @type and @id of each orderedItem against the Opportunity Data [[RPDE]] open feeds to retrieve the most up-to-date full Opportunity.

The Broker is expected to fully replace properties at the Order/OrderProposal level, in their entirety, as specified above, and MUST NOT perform a granular PATCH of nested properties within these. The rationale for this is that both this specification and the [[Modelling-Opportunity-Data]] specification on which this specification is based do not allow for explicit null values to exist within the model, which impedes property removal, and hinders any straightforward implementation of a granular PATCH.

Note that in this version of the specification, once an Order or OrderProposal has been created, only properties that are present in the Orders feed MAY be updated.

Note also that the representation of Orders within the Orders feed is designed specifically such that it does not include any personal data, except for that which is already available from the Opportunity Data [[RPDE]] open feeds provided by the Booking System.

Brokers MUST harvest the Orders feed with a frequency of at least once every 60 seconds to ensure expediency of updates and notifications to Customers.

Cancellation, replacement, refund calculation and notification

Regardless of the source of the cancellation, the process for refunding, notifying the Customer, and updating the Broker's records is exactly the same.

There are two scenarios that can update the effective OrderItem composition of an Order found in the Orders feed:

The Broker MUST process refunds for each new Cancellation or Replacement found in the feed, and it is the Broker's responsibility to continually retry failed refund processing and escalate any processing failure to the Customer accordingly. Note that the Orders feed is "fire and forget" for the Booking System: once an OrderItem is updated with a cancellation status in the Orders feed, the status MUST NOT be reversed, and is assumed by the Booking System to be processed.

For a Cancellation, the snapshot contents of acceptedOffer (and unitTaxSpecification, if relevant) within the OrderItems MUST remain unchanged by the Booking System after B, and new totalPaymentDue (and totalPaymentTax, if relevant) values MUST be calculated excluding OrderItems with an orderItemStatus of either https://openactive.io/CustomerCancelled or https://openactive.io/SellerCancelled.

For a Replacement, an updated acceptedOffer (and unitTaxSpecification, if relevant) MAY be included in the OrderItem, and MUST then constitute a snapshot and MUST remain unchanged by the Booking System except for in the case fo a further Replacement.

If the totalPaymentDue value of the Order has decreased (it is not permitted to increase) following one or more Cancellations or Replacements within an Order, the Broker MUST instruct the Payment Provider to issue a new Refund such that the new totalPaymentDue value of the Order is equal to the value of the associated Payment less all Refunds including the new one.

In all cases of the Order composition changing, the Broker MUST generate a new Invoice for the Order to replace the previous Invoice.

The Customer MUST be notified after a refund is successfully processed, with the Broker using the orderItemStatus or updated orderedItem to indicate the source of the refund.

If refund processing takes longer than 1 minute, then the Customer must be notified immediately of a Cancellation or Replacement ahead of the notification of the completed refund. This ensures the Seller can rely on the Broker as a notification channel. The Customer MUST be notified with the cancellationMessage (for Cancellation) or customerNotice (for Replacement) for the OrderItem, if provided.

Note that the Customer MUST be notified in the event of all Cancellations or Replacements, even if no refund is due (e.g. for Free Opportunities).

If the Booking System does not support Replacement, it MAY consistently exclude all three of the properties orderedItem, acceptedOffer and unitTaxSpecification from all OrderItems in the Orders feed.

Other notifications

The following properties within Orders in the Orders feed MAY also be updated by the Booking System, and MUST trigger the Broker to notify the Customer:

The following properties within Orders in the Orders feed MAY be updated by the Booking System, and MUST be reflected to the Customer in any user interface during their normal interaction with the Broker:

The following properties within Orders in the Orders feed MAY also be updated by the Booking System, and MUST be used subsequently by the Broker for their internal operations: