Open Booking API 1.0 CR

5.4.1 Customer Journey

The booking journey of a Customer is generalised into the following logical steps:

1. Select: Customer selects at least one Opportunity (e.g. ScheduledSession or Slot) and an associated Offer ("Junior (8-18) £9")
2. Identify: Customer submits personal details and other requested details
3. Book and Pay: Customer submits payment details

Note that some or all steps may be skipped, or may not be presented to the Customer, e.g. if their registration or payment details are already known, or they are using a voice interface. These steps are not indicative of the user experience, and simply provide a common language around the flow.

5.4.2 High-level API flow

• The Broker generates a UUID which is used to uniquely identify the Order throughout the process.

• After "1. Select" the Broker calls the Booking System to confirm an indicative price and the availability of the selected items using an OrderQuote, and retrieve a total order price. Any details that the Customer needs to supply to complete the booking are also specified. This is checkpoint C1 on the diagram above.

• After "2. Identify" the Broker calls the Booking System to reconfirm the price and availability of the selected items using an OrderQuote, using all personal details required, and retrieve a total order price. Explicit consent for any terms and conditions is also captured at this stage if required. This is checkpoint C2 on the diagram above.

• After "3. Book and Pay", the Broker first pre-authorizes the payment for the total order price (if required by the Payment Provider), then confirms the booking with the Booking System using an Order (B on the diagram above), and finally captures the payment. The Broker then generates invoices, and sends the Customer notifications.

• The Booking System adds the Order to an Orders feed specific to the Broker, which the Broker reads to update its internal state, including those updates resulting from cancellations.

5.4.3 Leasing

Customers may simultaneously attempt to book the same Opportunity (e.g. space in an event or Slot of a facility), and hence contend with one another for a limited number of Opportunities. In order to ensure that items cannot be "stolen" from a Customer's "shopping basket" by another Customer, some Booking Systems use the concept of a Lease, a temporary reservation that provides a window during which a Customer can complete their customer journey and improves the user experience overall.

The design of this API supports the use of time-bound Leases. Using Leases is RECOMMENDED, however they are not required, in order to ensure a low barrier of entry for implementors of the specification.

Individually at C1 and C2, the Booking System can opt to create (or extend) a Lease for the Broker. Whether they opt to do so may depend on the Booking System's capacity to support Leases, or on the Seller's configuration of the Booking System.

At C1 an Anonymous Lease MAY be created i.e. a Lease for a Customer that has not yet provided any personal details.

At C2 a Named Lease MAY be created i.e. a Lease for a Customer who has identified themselves via personal details and other additional details. Any existing Anonymous Lease becomes a Named Lease when the customer's personal details are provided (even if the Booking System does not store them at this stage).

If a Lease is created at C1 and/or C2 it is used during B. However, if no Lease is created, or if it had expires prior to the transaction being completed, the booking completes anyway provided sufficient inventory is available.

It is RECOMMENDED that if the Booking System supports leasing, it also guarantees the price of each leased item for the duration of the Lease, so that the Customer is guaranteed to pay the price they have seen during C2.

The specification is designed to allow Brokers to be agnostic to Leases: should a Booking System be upgraded to support these, it can do so without affecting the Broker's implementation.

By design, then, the use of Leases is largely transparent to the Broker. However, the Booking System MUST provide information on the Lease to help improve the user experience of the customer journey as follows: when a Lease is created, a Lease object MUST be returned in the OrderQuote.

"lease": {
  "type": "Lease",
  "leaseExpires": "2018-10-01T11:00:00Z"
}

The leaseExpires MAY be used to inform the Customer of the time they have remaining.

5.4.4 High-level type flow

The OrderQuote is an ephemeral draft of the Order while it is being constructed by the Customer.

• C1 - OrderQuote without enough personal details or additional details to be accepted as an Order.
• C2 - OrderQuote with complete and validated detail, enough to be created successfully as an Order.
• B - Order exists in an instantly successful state in the Booking System, though it transitions through orderCreationStatus states in the Broker.

5.4.5 Order statuses

To simplify the implementation for the Booking System, the creation of an Order is considered atomic to the Booking System (it succeeds or fails at once in B), and by contrast is considered to consist of steps to the Broker.

5.4.6 Step-by-step process description

i) "1. Select" - Customer browses Broker site anonymously and adds something to basket

• Broker MUST have determined at least one Open Booking bookable Opportunity each with an associated applicable Offer from the Customer's browsing, using the most up-to-date Opportunity Data.
• Broker generates a UUID to use for the Order.
• If any catastrophic failure occurs during the booking flow (any error with status code 500, or when the request consistently returns status code 503 after a number of retries) the UUID MUST be regenerated to allow for a clean retry of the booking. UUID MUST NOT be regenerated for expected errors (status code 4xx).

ii) C1 - Broker call with OrderQuote including UUID without a customer object to check availability and that the combination of items requested can be purchased, Booking System responds with an OrderQuote including any errors against each OrderItem.

• Booking System creates Anonymous Lease for that UUID if it is supported, otherwise it provides a simple availability and totalPaymentDue confirmation. An OrderQuote response with HTTP Status 200 will be returned if the all requested items are available. If a Lease has been created, then the OrderQuote in the response MUST include a lease property containing a valid Lease object.
• OrderQuote MUST include totalPaymentDue, which allows the Broker to update any UI with the total.
• OrderQuote MUST include a list of OrderItems which contain their respective Opportunity objects, including enough detail to allow the Broker to communicate key information about the Opportunity to the Customer (rather than relying on the Broker having the most up-to-date Opportunity data from the open feeds at the point of purchase).
• The Booking System MUST ensure that the data returned to the Broker in the remainingAttendeeCapacity and remainingUses properties are up-to-date, including places already booked and those currently reserved by any Leases from competing OrderQuotes.
• OrderQuote MUST specify any additional details required to complete the booking for the selected OrderItems via an orderItemIntakeForm.
• If there are any issues with the OrderItems requested in the OrderQuote, the Booking System MUST respond with a 409 Conflict response, with error details provided against each offending OrderItem.
• The Booking System MUST reflect back all properties defined by this specification that are supplied by the Broker's request in its response, including broker and brokerRole, to acknowledge they have been recognised (even if they have not actually been stored by the Booking System). The Booking System MUST NOT reflect back extension properties outside of this specification unless it explicitly supports them.
• Where totalPaymentDue is not 0, and the prepayment value of any Offer is https://openactive.io/Required or unspecified, the payment details supplied to C2 (e.g. accountId) MUST be supplied at C1, otherwise an IncompletePaymentDetailsError MUST be returned. This ensures that a viable payment reconciliation route is available before the Customer starts to enter their data. If the payment details supplied (e.g. accountId) are not considered valid for reconciliation by the Booking System then a InvalidPaymentDetailsError MUST be returned.
• OrderItems have no orderItemStatus.

iii) "2. Identify" - Customer submits personal details and any other additional details requested

• The Customer MUST have been informed that their personal information is being submitted to the Seller.
• The Customer MUST have been made aware of any relevant termsOfService, for example by displaying a link to them prominently, before submitting their personal details.
• If requiresExplicitConsent is true for any termsOfService then the Customer MUST only be allowed to proceed if they have explicitly acted to assent to such terms.
• attendee and orderItemIntakeFormResponse data is be captured at this stage if specified via attendeeDetailsRequired and orderItemIntakeForm in the C1 response, respectively.
• If prepayment of all selected Offers is https://openactive.io/Optional where they are not https://openactive.io/Unavailable then the Customer MAY be given the option to prepay or simply reserve a space without payment. Providing optionality of payment to the Customer is at the Broker's discretion.

iv) C2 - Broker call with OrderQuote including UUID with a customer object and any orderItemIntakeFormResponse required, Booking System responds with an OrderQuote including any errors against each OrderItem.

• Booking System creates Named Lease for that UUID if it is supported, otherwise it provides a simple availability and totalPaymentDue confirmation. Works exactly as C1, except validates payment details, customer details, any attendee details, and the orderItemIntakeFormResponse.
• Broker presents the contents of the OrderQuote to the Customer to ensure they have the most up-to-date price and availability before proceeding with the purchase.
• If there are any issues with the OrderItems requested in the OrderQuote, the Booking System MUST respond with a 409 Conflict response, with error details provided against each offending OrderItem - including if an OrderItem is no longer available, cannot be purchased in combination with another OrderItem, or does not contain a sufficient orderItemIntakeFormResponse.
• Any errors must be resolved by the Customer or Broker before proceeding, by amending the OrderItems included in the OrderQuote and resubmitting until an OrderQuote is returned without errors.
• In the case that payment is selected (or if the prepayment value of any selected Offer is https://openactive.io/Required or unspecified), the payment property MUST be included in the OrderQuote request and response including all details except the identifier, to express the intent to pay. If the payment property is omitted where totalPaymentDue is not 0, and the prepayment value of any Offer is https://openactive.io/Required or unspecified, then a IncompletePaymentDetailsError MUST be returned. If the payment details supplied (e.g. accountId) are not considered valid for reconciliation by the Booking System then a InvalidPaymentDetailsError MUST be returned.
• OrderItems have no orderItemStatus.

v) "3. Book and Pay" - Customer submits payment details and clicks Book

• The Customer MUST only be allowed to proceed if no OrderItems in the OrderQuote contain any errors.

• If totalPaymentDue is 0 because all OrderItems are free of charge, prepayment of all selected Offers is either https://openactive.io/Unavailable or https://openactive.io/Optional, or the Customer has chosen not to pay, payment details MUST NOT be captured.

vi) Payment Authorisation - Broker pre-authorises totalPaymentDue from Payment Provider

• The Order id, which includes the UUID, and will be generated by the Broker to make the PUT call at B (the Order id is also the PUT endpoint URL), SHOULD be used as a reference in the Payment Provider, if possible.

• If payment details were not captured due to the prepayment value of the selected Offers or totalPaymentDue equalling 0, pre-authorisation MUST NOT be taken.

• The Broker MUST store the Order request with an orderCreationStatus of https://openactive.io/OrderCreationPaymentAuthorized at this point, even if pre-authorisation is not taken, in order to ensure that the UUID in the Orders feed is recognised without a race condition. Such a condition might arise in the (admittedly unlikely) event of, e.g., an Order that is created at B and then immediately cancelled by the Booking System, which could result in the Broker receiving an unrecognised Order in the Orders feed if it was retrieved before the call to B returned.

vii) B - Broker call with an Order including UUID with a customer object and any orderItemIntakeFormResponse required, and totalPaymentDue including the total amount pre-authed; the Booking System responds with an Order.

• If payment details were not captured due to the prepayment value of the selected Offers, or if totalPaymentDue is 0 due to all OrderItems being free of charge, the payment property MUST NOT be included in the Order request or response. If the payment property is omitted where totalPaymentDue is not 0, and the prepayment value of any Offer is https://openactive.io/Required or unspecified, then an IncompletePaymentDetailsError MUST be returned. If the payment details supplied (e.g. accountId) are not considered valid for reconciliation by the Booking System then an InvalidPaymentDetailsError MUST be returned.

• The identifier of the Payment is taken from the payment pre-authorization, which must be able to be matched against any payment reports produced by the Payment Provider for the purposes of audit and/or reconciliation.

• If the totalPaymentDue included in the Order object is different to the current totalPaymentDue (which might have changed since C2, e.g. if the headline price is changed in the Booking System between these two steps), B returns an TotalPaymentDueMismatchError with associated status code, but the Lease is sustained so that the Customer can be prompted whether they want to continue with the new amount.

• If the Lease has expired, or if Leases are not supported, then the Booking System attempts to make the booking anyway. If there are insufficient spaces available for OrderItems the B returns an OpportunityHasInsufficientCapacityError with associated status code.

• If the booking succeeds only for some OrderItems, the whole transaction to create the Order within the Booking System is rolled back and B returns an OrderCreationFailedError with associated status code.

• If there's a network failure, e.g. no response from server, then the Broker can resubmit with same UUID. As the call is idempotent, the Booking System will need to track the UUID supplied by Broker against any successfully created Orders, to ensure that it can return the same Order for subsequent requests. The Broker MUST NOT reuse UUIDs across multiple Orders.

• If the call is successful (returns a 200 response), the booking is considered as complete and paid by the Booking System at this point.

• The Booking System MUST reflect back all properties defined by this specification that are supplied by the Broker's request in the Order returned from this call, including broker and brokerRole, to acknowledge they have been recognised (even if they have not actually been stored by the Booking System). The Booking System MUST NOT reflect back extension properties outside of this specification unless it explicitly supports them.

• The Order returned from this call MUST be stored by the Broker, to be subsequently updated by the Orders feed. The Orders feed contains only partial-updates of the Order stored by the Broker, and the Broker is the only actor guaranteed to maintain a complete view of the Order. The Booking System MAY store the full Order if desired.

• It is the responsibility of the Broker to store any additional state it requires that is not included in the Order returned from this call, and RECOMMENDED that such state is stored alongside the Broker's persisted Order.

• The Broker MUST store the Order response in with an orderCreationStatus of https://openactive.io/OrderCreationPaymentDue at this point (or https://openactive.io/OrderCreationPaymentCaptured if no payment is due).

• This call is idempotent, and hence if the UUID used for an Order already represents a completed Order with the same set of OrderItems for the same customer as those specified, the success response is returned as normal. If any differences exist in the Orders, a UUID clash is assumed, a 500 response of with OrderAlreadyExistsError is returned by the Booking System, and a new UUID must be generated by the Broker to retry the call.

• As this call is idempotent, it can be safely retried in the case of an temporary unexpected error (any error that returns status code 503) or rate limiting (any error that returns status code 429).

• When the request still returns status code 503 after a number of retries the UUID MUST be regenerated to allow for a clean retry of the booking. The UUID MUST NOT be regenerated for expected errors (status code 4xx).

• OrderItems returned by the Booking System have an orderItemStatus of https://openactive.io/OrderConfirmed.

viii) Payment Capture - Broker captures totalPaymentDue from Payment Provider

• It is the Broker's responsibility to ensure that payment has been captured if required.

• If payment is required, the Broker MUST update its stored Order with an orderCreationStatus of https://openactive.io/OrderCreationPaymentCaptured after payment is successfully captured.

• If payment details were not captured due to the prepayment value of the selected Offers or totalPaymentDue equalling 0, payment MUST NOT be captured.

ix) Invoice Generation and Customer Notification - Upon successful Payment Capture (or completing B in the case of payment capture not being required), the Broker generates invoices, sends the Customer notifications, and stores the Order in a success state based on the response from B.

• The Broker MUST update its stored Order in with an orderCreationStatus of https://openactive.io/OrderDelivered after invoices have been created and notifications successfully sent.

x) Refunds and Cancellation - The Broker subscribes to updates from the Booking System to process cancellations and refunds.

• A secure Orders feed of Orders MUST be provided by the Booking System, with the contents of the feed specific to the authentication credentials. This allows the Broker to maintain an updated state of all their bookings across a number of Booking Systems, even when changes are made outside of the Broker. This also allows the Broker to handle refunds for cancellations, and process notifications to Customers in a consistent way.
• The Booking System must ensure that the Orders in the Orders feed represent the current state of OrderItems within the system, for the properties included in the feed. The Broker MUST use these Orders to process refunds and send update notifications to the Customer.

5.4.7 Booking Flow Rollback

To ensure catastrophic errors are detected and resolved the Broker MUST periodically check its own store for any Orders that have not been updated in over a 2 minutes, and have an orderCreationStatus other than https://openactive.io/OrderCreationComplete.

Note that due to the ordering of the Booking Flow, no notifications will have been sent to the Customer, so no notifications regarding the rollback are required assuming it is performed promptly.

5.4.8 Contracts

A summary of the key conformance criteria for the Broker and Booking System is included here.

5.5.1 Customer Journey

The booking journey of a Customer is generalised into the following logical steps:

The steps exactly mirror the Simple Booking Flow, with two additions in the 'Identify' step:

1. Select: Customer selects at least one Opportunity (e.g. ScheduledSession or Slot) and an associated Offer ("Junior (8-18) £9")
2. Identify: Customer submits personal details and other requested details
3. Propose: Customer submits payment details, and submits a proposed booking
4. Approve: Seller approves the booking, after a period of time
5. Book and Pay: Customer confirms they are happy to proceed

Note that some or all steps may be skipped, or may not be presented to the Customer, e.g. if their registration or payment details are already known, or they are using a voice interface. These steps are not indicative of the user experience, and simply provide a common language around the flow.

5.5.2 High-level API flow

The flow exactly mirrors the Simple Booking Flow, with two additions:

• The Broker generates a UUID which is used to uniquely identify the Order throughout the process.

• After "1. Select" the Broker calls the Booking System to confirm an indicative price and availability of the selected items using an OrderQuote, and retrieve a total order price. Any details that the Customer needs to supply to complete the booking are also specified. This is checkpoint C1 on the diagram above.

• After "2. Identify" the Broker calls the Booking System to reconfirm the price and availability of the selected items using an OrderQuote, using all details required, and retrieve a total order price. Explicit consent for any terms and conditions is also captured at this stage if required. This is checkpoint C2 on the diagram above.

• After "2.1. Propose", the Broker first pre-authorizes the payment for the total order price (if required by the Payment Provider), then submits the proposed booking to the Booking System using an OrderProposal (P on the diagram above), and sends the Customer a notification that the proposal is under consideration. The OrderProposal may be negotiated between the Customer and Seller via the Broker at this stage.

• After "2.2. Approve" the Seller approves the OrderProposal and the Broker is notified of this by the Booking System (A on the diagram above). The Broker can seek Customer permission to proceed, or simply complete the booking automatically, depending on the desired user experience.

• After "3. Book and Pay", if necessary the Broker re-authorizes the payment for the total order price (if it has changed, and if required by the Payment Provider), then confirms the booking with Booking System using an Order (B on the diagram above), and finally captures the payment. The Broker then generates invoices, and sends Customer notifications.

• The Booking System adds the Order to an Orders feed specific to the Broker, which the Broker reads to update its internal state, including those updates resulting from cancellations.

Note that the OrderProposal at stages 2.1 and 2.2 does not constitute a booking. The whole flow MUST be completed before the Customer is considered "booked" onto an Opportunity.

5.5.3 Proposal Leasing

Leasing works as specified in the Simple Booking Flow, and if a Lease was acquired at C1 or C2 it SHOULD be carried over to the OrderProposal and the Lease extended for a duration sufficient to cover the lifetime of the OrderProposal.

A Lease is NOT REQUIRED for this flow, as in some cases Sellers may prefer to manage contention for spaces manually via the approval process instead of leasing.

If an OrderProposal is in an orderProposalStatus other than https://openactive.io/CustomerRejected or https://openactive.io/SellerRejected, regardless of whether or not the Lease has expired, it MUST be possible for the Customer to still complete the booking if they attain approval. If at any point this is not the case, it is the responsibility of the Booking System to set the orderProposalStatus to https://openactive.io/SellerRejected, or if openBookingFlowRequirement of any Offer referenced in the OrderProposal includes https://openactive.io/OpenBookingNegotiation, to update the OrderProposal to remove or replace the offending OrderItem(s) with an appropriate orderSellerNote. For example, if an Opportunity becomes full or is cancelled and no substitute Opportunities are available, then all remaining outstanding OrderProposals related to that Opportunity would need to be automatically rejected or updated.

If the Lease expires the Booking System could, for example, automatically reject the OrderProposal on behalf of the Seller, automatically renew the Lease, or allow the Seller to manually deal with the contention for spaces as part of the approval process and hence do nothing.

5.5.4 High-level type flow

As specified in the Simple Booking Flow, with one addition:

• P/A - OrderProposal exists in a number of states, as described in the next section, and contains enough detail to successfully create an Order.

5.5.5 OrderProposal statuses

OrderProposal has an orderProposalStatus which is initially set by the Booking System to https://openactive.io/AwaitingSellerConfirmation.

The Broker MUST only proceed to B when orderProposalStatus is set to https://openactive.io/SellerAccepted in the Orders feed.

An OrderProposal MUST be approved or rejected atomically; partial approval is not supported in this version of the specification (though Proposal Amendment is supported).

To reach the criteria to proceed to B, or rejection, OrderProposal MUST be transitioned through states as follows:

• The Booking System MUST transition the OrderProposal to a new orderProposalStatus by updating the Orders feed.
• The Broker MUST transition the OrderProposal to a new orderProposalStatus by submitting a PATCH to the OrderProposal using the OrderProposal Update endpoint.

5.5.6 Step-by-step process description

For an Order that requires approval, the flow differs from the Simple Booking Flow, and proceeds as follows:

i-iv) The steps 1. Select; C1; 2. Identify; and C2 of this flow are exactly the same as Simple Booking Flow steps i-iv, except that OrderQuote is returned at C1 and C2 with orderRequiresApproval set to true if any OrderItems require approval. In this case, the next step after C2 MUST be to follow the Booking Flow with Approval.

• The Booking System MUST include the openBookingFlowRequirement of https://openactive.io/OpenBookingApproval for any Offers that require this flow. This allows Brokers that do not support approval to easily filter out such offers from their experience.

• For the avoidance of doubt, as in the Simple Booking Flow:

• Additional data is supplied at C2 to satisfy the orderItemIntakeForm for all OrderItems in C1.

• The totalPaymentDue from C2 is used for initial Payment Authorisation.

v) "2.1. Propose" - Customer submits payment details, and submits an initial booking in the form of an OrderQuote.

• For the avoidance of doubt, as in the Simple Booking Flow:

• The Customer MUST only be allowed to proceed if no OrderItems in the OrderQuote contain any errors.

• If totalPaymentDue is 0 because all OrderItems are free of charge, prepayment of all selected Offers is either https://openactive.io/Unavailable or https://openactive.io/Optional, or the Customer has chosen not to pay, payment details MUST NOT be captured.

vi) Payment Authorisation - Broker pre-authorises totalPaymentDue from Payment Provider.

This proceeds almost exactly as in the Simple Booking Flow, except that instead of an Order, an OrderProposal (subclassing Order) is created by the Broker.

• As in the Simple Booking Flow, the OrderProposal id, which includes the UUID and is generated by the Broker to make the PUT call at B (the OrderProposal id is also the PUT endpoint URL), SHOULD be used as a reference in the Payment Provider, if possible.

• As in the Simple Booking Flow, the Broker MUST store the OrderProposal at this point even if pre-authorisation is not taken, in order to prevent the possibility of a race condition. However, note that orderCreationStatus MUST NOT be set on the OrderProposal.

vii) P - The Broker makes a request containing its newly-created OrderProposal, including its UUID, a customer object, any orderItemIntakeFormResponse required, and totalPaymentDue including the total amount pre-authed. The Booking System responds in turn with an OrderProposal with orderProposalStatus set to https://openactive.io/AwaitingSellerConfirmation.

• The Broker MUST store this returned OrderProposal.

• The call is atomic.

• The returned OrderProposal also contains an orderProposalVersion (constructed from the id of the OrderProposal, combined with an additional version UUID).

• OrderItems returned have an orderItemStatus of https://openactive.io/OrderProposed.

• If the call is successful (returns a 200 response), the booking MUST NOT be considered as complete by the Booking System at this point, and instead MUST be considered in a 'proposed' state.

• The Broker MUST NOT store an orderCreationStatus against the OrderProposal.

• The OrderProposal MAY include an orderCustomerNote in order to allow the Customer to ask a question about this Opportunity, as the beginning of a Message Exchange, if the openBookingFlowRequirement of any Offer referenced in the OrderProposal includes https://openactive.io/OpenBookingMessageExchange.

• To match much of the behaviour of B in the Simple Booking Flow, the following also apply:

• The OrderProposal from P will not be present in the Orders feed until it is updated at least once.

• totalPaymentDue MUST be submitted to P and MUST match the value calculated by the Booking System to ensure that the totalPaymentDue has not changed.

• If payment details were not captured due to the prepayment value of the selected Offers, or if totalPaymentDue is 0 due to all OrderItems being free of charge, the payment property MUST NOT be included in the OrderProposal request or response. If the payment property is omitted where totalPaymentDue is not 0, and the prepayment value of any Offer is https://openactive.io/Required or unspecified, then an IncompletePaymentDetailsError MUST be returned. If the payment details supplied (e.g. accountId) are not considered valid for reconciliation by the Booking System then an InvalidPaymentDetailsError MUST be returned.

• The identifier of the Payment is taken from the payment pre-authorization, which must be able to be matched against any payment reports produced by the Payment Provider for the purposes of audit and/or reconciliation.

• If the totalPaymentDue included in the Order object is different to the current totalPaymentDue (which might have changed since C2, e.g. if the headline price is changed in the Booking System between these two steps), P returns an TotalPaymentDueMismatchError with associated status code, but the Lease is sustained so that the Customer can be prompted whether they want to continue with the new amount.

• If the Lease has expired, or if Leases are not supported, then the Booking System attempts to create the OrderProposal anyway. If there are insufficient spaces available for OrderItems the P returns an OpportunityHasInsufficientCapacityError with associated status code.

• If the booking succeeds only for some OrderItems, the whole transaction to create the OrderProposal within the Booking System is rolled back and P returns an OrderCreationFailedError with associated status code.

• If there's a network failure, e.g. no response from server, then the Broker can resubmit with same UUID. As the call is idempotent, the Booking System will need to track the UUID supplied by Broker against any successfully created OrderProposals, to ensure that it can return the same OrderProposal for subsequent requests. The Broker MUST NOT reuse UUIDs across multiple OrderProposals.

• The Booking System MUST reflect back all properties defined by this specification that are supplied by the Broker's request in the OrderProposal returned from this call, including broker and brokerRole, to acknowledge they have been recognised (even if they have not actually been stored by the Booking System). The Booking System MUST NOT reflect back extension properties outside of this specification unless it explicitly supports them.

• The OrderProposal returned from this call MUST be stored by the Broker, to be subsequently updated by the Orders feed. The Orders feed contains only partial-updates of the OrderProposal stored by the Broker, and the Broker is the only actor guaranteed to maintain a complete view of the OrderProposal. The Booking System MAY store the full OrderProposal if desired.

• It is the responsibility of the Broker to store any additional state it requires that is not included in the OrderProposal returned from this call, and RECOMMENDED that such state is stored alongside the Broker's persisted Order.

• This call is idempotent, and hence if the UUID used for an OrderProposal already represents a completed OrderProposal with the same set of OrderItems for the same customer as those specified, the success response is returned as normal. If any differences exist in the OrderProposals, a UUID clash is assumed, a 500 response of with OrderAlreadyExistsError is returned by the Booking System, and a new UUID must be generated by the Broker to retry the call.

• As this call is idempotent, it can be safely retried in the case of an temporary unexpected error (any error that returns status code 503) or rate limiting (any error that returns status code 429).

• When the request still returns status code 503 after a number of retries the UUID MUST be regenerated to allow for a clean retry of the booking. The UUID MUST NOT be regenerated for expected errors (status code 4xx).

viii) "2.2. Approve" - Seller approves the booking after automated or manual review.

• The Booking System must ensure that the OrderProposals in the Orders feed represent the current state of OrderProposal within the system. The Broker MUST use these OrderProposals to process orderProposalStatus changes and send update notifications to the Customer, including any new values for orderSellerNote.

• Once approved, the Booking System puts the updated OrderProposal onto the Orders feed (A), with either an unchanged orderProposalVersion (see Minimal Proposal Implementation) or a new orderProposalVersion (see Proposal Amendment).

• If the orderProposalVersion in the Orders feed has changed compared with the orderProposalVersion in the OrderProposal stored by the Broker, the Broker MUST notify the Customer that their booking requires confirmation before it can proceed. The Broker MUST detect and highlight any changes from their stored OrderProposal in the notification, based on the difference between the OrderItems stored by the Broker and those in the feed.

ix) "3. Book and Pay" - Customer confirms booking

• The Broker MUST only proceed when orderProposalStatus is set to https://openactive.io/SellerAccepted in the Orders feed, and the orderProposalVersion is set to a value the Customer has agreed to (see Proposal Amendment).

• If totalPaymentDue is 0 because all OrderItems are free of charge, prepayment of all selected Offers is either https://openactive.io/Unavailable or https://openactive.io/Optional, or the Customer has chosen not to pay, payment details MUST NOT be captured.

x) Payment Re-authorisation - Broker re-authorises totalPaymentDue from Payment Provider as necessary

• The Broker MUST re-authorise the totalPaymentDue, if it has increased in the new orderProposalVersion that the Customer has agreed to (see Proposal Amendment), or if the previous Payment Authorisation has expired.

• As with the Simple Booking Flow, the Broker MUST store the Order request with an orderCreationStatus of https://openactive.io/OrderCreationPaymentAuthorized at this point, even if pre-authorisation is not taken, in order to ensure that the UUID in the Orders feed is recognised without a race condition.

xi) B - The Broker makes a minimal call with an Order consisting of only the orderProposalVersion and any additional payment data from the re-authorisation step if necessary; the Booking System responds with a full Order as per the Simple Booking Flow.

• If the Lease has expired, or if Leases are not supported, then the Booking System attempts to make the booking anyway. If there are insufficient spaces available for OrderItems the B returns an OpportunityHasInsufficientCapacityError with associated status code and the original OrderProposal MUST be rejected by the Seller as per Proposal Leasing. Note that this is unlikely to occur as in such cases the OrderProposal SHOULD have already been rejected when it could no longer be fulfilled.

• The Booking System MUST reflect back all properties defined by this specification that were supplied in the Broker's original OrderProposal request (with amendments if Proposal Amendment has occurred), to acknowledge they have been recognised. The Booking System MUST NOT reflect back extension properties outside of this specification unless it explicitly supports them.

• All other behaviour is identical to the Simple Booking Flow step vii.

xii-xiv) The Payment Capture, Invoice Generation, Customer Notification, and Refunds and Cancellation steps of this flow are exactly the same as Simple Booking Flow steps viii-x.

Booking Flow Rollback also applies to this flow exactly as in the Simple Booking Flow.

5.5.7 Contract

A summary of the key conformance criteria is included here. These apply for the Booking Flow with Approval in addition to the contract specified in the Simple Booking Flow.

5.6.1 Customer Details capture

The specification includes provision to capture of the following details related to the Customer (the actor who is booking), with only the e-mail address being required.

• E-mail address (email)
• Forename (givenName)
• Surname (familyName)
• Telephone (telephone)

Note that these are not the details of attendees, and that the Customer is not guaranteed to participate in the activity. This facilitates child booking as the Customer can easily book on behalf of a child, without supplying the child's own personal details.

5.6.2 Attendee Details capture

If attendee details in scope of the Person type are captured, they MUST be captured via the attendee property of the OrderItem (and not using the orderItemIntakeForm). This allows attendee details to be stored and reused by the Broker.

Note that conformance with this specification requires that the Booking System MUST NOT require attendee data to be submitted in all cases, and that configuration of which attendee details are required (if any) MUST be available to the Seller.

If an Offer requires attendee details capture, the Booking System MUST include the openBookingFlowRequirement of https://openactive.io/OpenBookingAttendeeDetails in the Offers within its open data. This allows Brokers that do not support attendee details capture to easily filter out such offers from their experience.

{
  "type": "OrderItem",
  ...
  "attendeeDetailsRequired": [
    "https://schema.org/givenName",
    "https://schema.org/familyName"
  ],
}

{
  "type": "OrderItem",
  ...
  "attendee": {
    "type": "Person",
    "email": "[email protected]",
    "telephone": "020 811 8055",
    "givenName": "Geoff",
    "familyName": "Capes"
  }
}

If a required property within Person is not supplied by the Broker the Booking System MUST include an IncompleteAttendeeDetailsError against the offending OrderItem at C2 which includes an instance that references the id of the missing or invalid Property.

{
  "type": "OrderItem",
  ...
  "error": [
    {
      "type": "IncompleteAttendeeDetailsError",
      "instance": "https://schema.org/givenName",
      "description": "Missing attendee first name"
    }
  ]
}

The Broker MAY remember the attendee data previously submitted by the Customer, if consent is provided.

5.6.3 Additional Details capture

This version of the specification does not provide comprehensive support for construction of a complex additional details capture form. However, it does facilitate the use of simple text fields, dropdowns and checkboxes to capture additional details. These can be used for both the Simple Booking Flow and the Booking Flow with Approval.

If an Offer requires additional details capture, the Booking System MUST include the openBookingFlowRequirement of https://openactive.io/OpenBookingIntakeForm in the Offers within its open data. This allows Brokers that do not support such additional details capture to easily filter out such offers from their experience.

Four types of form element are available, all of which sub-class PropertyValueSpecification:

• ShortAnswerFormFieldSpecification
• ParagraphFormFieldSpecification
• DropdownFormFieldSpecification
• BooleanFormFieldSpecification

{
  "type": "OrderItem",
  ...
  "orderItemIntakeForm": [
    {
      "type": "ShortAnswerFormSpecification",
      "id": "https://example.com/experience",
      "name": "Level of experience",
      "description": "Have you played before? Are you a complete beginner or seasoned pro?",
      "valueRequired": true
    }
  ]
}

{
  "type": "OrderItem",
  ...
  "orderItemIntakeFormResponse": [
    {
      "type": "PropertyValue",
      "propertyID": "https://example.com/experience",
      "value": "I've played twice before, but I'm a quick learner so I hope to keep up!"
    }
  ]
}

{
  "type": "OrderItem",
  ...
  "orderItemIntakeForm": [
    {
      "type": "DropdownFormFieldSpecification",
      "id": "https://example.com/age",
      "name": "Age",
      "description": "Your age is useful for us to place you in the correct group on the day",
      "valueOption": ["0-18", "18-30", "30+"],
      "valueRequired": true
    }
  ]
}

{
  "type": "OrderItem",
  ...
  "orderItemIntakeFormResponse": [
    {
      "type": "PropertyValue",
      "propertyID": "https://example.com/age",
      "value": "0-18"
    }
  ]
}

{
  "type": "OrderItem",
  ...
  "orderItemIntakeForm": [
    {
      "type": "BooleanFormFieldSpecification",
      "id": "https://example.com/photoconsent",
      "name": "Photo Consent",
      "description": "Are you happy for us to include photos of you in our marketing materials?"
    }
  ]
}

{
  "type": "OrderItem",
  ...
  "orderItemIntakeFormResponse": [
    {
      "type": "PropertyValue",
      "propertyID": "https://example.com/photoconsent",
      "value": true
    }
  ]
}

{
  "type": "OrderItem",
  ...
  "error": [
    {
      "type": "IncompleteIntakeFormError",
      "instance": "https://example.com/experience",
      "description": "Incomplete additional details supplied"
    }
  ]
}

{
  "type": "OrderItem",
  ...
  "error": [
    {
      "type": "InvalidIntakeFormError",
      "instance": "https://example.com/shoesize",
      "description": "The provided shoe size is not a number"
    }
  ]
}

6.1.1 Definition

A reseller is a company or individual that purchases goods or services with the intention of selling them rather than consuming or using them. This is usually done for profit (but could be resold at a loss).

6.1.2 Contractual Relationships

In the context of OpenActive, a ResellerBroker contracts directly with the Seller as a business-to-business relationship to purchase access to the Opportunity. It then, at a later point in time (which may only be milliseconds later), separately forms a contractual relationship with the Customer, who purchases access to the Opportunity from the ResellerBroker.

6.1.3 Taxation

The ResellerBroker's purchase from the Seller is business-to-business, which is subject to the appropriate taxation based on the ResellerBroker as the Customer. The Customer's purchase from the ResellerBroker is business-to-consumer, which is subject to the appropriate taxation based on the ResellerBroker as the Seller.

Hence any tax exemption that the Customer may enjoy when purchasing directly from the Seller (e.g. in UK law, if the Seller is a VAT exempt eligible body) is not relevant here, as no direct contractual relationship is formed between Seller and Customer.

6.1.4 Scope of Specification

This specification is designed to govern the interaction between the ResellerBroker and Seller. It does not include provision for the interaction between the ResellerBroker and Customer explicitly, though it may be repurposed by the Broker to perform this function by treating the Broker as a Booking System. This specification also does not include provision for the recording of the execution of the contractual relationship with any Payment Provider (e.g. for payment processing fees). Such relationships MUST be handled separately. When the brokerRole is set to ResellerBroker, this indicates that the payee for accounting and tax purposes is the broker specified in the Order. Note that the customer may still optionally be included in the Order, for example to help front-of-house staff identify the Customer.

6.1.5 Conformance criteria

When the Broker generates the Invoice, it must be made payable to Order.broker, Order.broker MUST be provided and Order.customer is optional.

6.2.1 Definition

An agent is authorized to act on behalf of another (the Seller, or "principal") to create legal relations with a third party (the Customer). Succinctly, it may be referred to as the equal relationship between a Seller and an agent whereby the principal, expressly or implicitly, authorizes the agent to work under his or her control and on his or her behalf. The agent is required to negotiate on behalf of the principal (Seller) and/or bring them and third parties (Customers) into contractual relationship.

6.2.2 Contractual Relationships

There are three separate types of contractual relationship involved: AgentBroker with Seller, known as the principal-agent relationship or "internal" relationship; AgentBroker with Customer with whom they deal on their Seller's behalf ("external relationship"); and Seller with Customer when arranged by an AgentBroker.

6.2.3 Taxation

While facilitated by the AgentBroker, the primary purchase is made by the Customer directly from the Seller, as would be the case if the Customer was to purchase from the Seller independently. Hence any tax exemption that the Customer may enjoy when purchasing directly from the Seller (e.g. in UK law, if the Seller is an VAT exempt eligible body) is relevant here.

The Customer's relationship with AgentBroker is business-to-consumer. Hence any additional services (e.g. customer-facing booking fees) are subject to the appropriate taxation based on the AgentBroker as the seller.

The AgentBroker's relationship with the Seller is business-to-business. Hence any additional services (e.g. booking commission) are subject to the appropriate taxation.

6.2.4 Scope of Specification

This specification is designed to govern the recording of the execution of the contractual relationship between the Customer and Seller. The scope of this specification does not include the contractual relationship between the AgentBroker and the Seller (e.g. for booking commission), between the AgentBroker and the Customer (e.g. for booking fees) or with any Payment Provider (e.g. for payment processing fees). Such relationships and the reconciliation of associated invoices MUST be handled separately. When the brokerRole is set to AgentBroker, this indicates that the payee for accounting and tax purposes is the customer specified in the Order.

6.2.5 Conformance criteria

When the Broker generates the Invoice, it must be made payable to Order.customer, Order.broker MUST be provided and Order.customer MUST be provided.

6.2.6 Informed purchase

When using a brokerRole of AgentBroker, the Broker MUST make the Customer aware that they are purchasing directly from the Seller via the Broker, and not directly from the Broker.

6.3.1 Definition

This specification supports direct purchase by a Customer (for example in the context of the Seller's own website, or for businesses that purchase large volumes of FacilityUse slots to run leagues).

6.3.2 Contractual Relationships

The contractual relationship is a simple one between the Seller and the Customer.

6.3.3 Taxation

The purchase is made by the Customer directly from the Seller, as would be the case if the Customer was to purchase from the Seller outside of this specification. Hence any tax exemption that the Customer may enjoy when purchasing directly from the Seller (e.g. in UK law, if the Seller is an VAT exempt eligible body) is relevant here.

6.3.4 Scope of Specification

This specification is designed to govern the recording of the execution of the contractual relationship between the Customer and Seller. The scope of this specification does not include the contractual relationship with any Payment Provider (e.g. for payment processing fees). Such relationships MUST be handled separately.

When the brokerRole is set to NoBroker, this indicates that the payee for accounting and tax purposes is the customer specified in the Order.

6.3.5 Conformance criteria

When an Invoice is generated, it must be made payable to Order.customer, Order.broker MUST NOT be provided and Order.customer MUST be provided.

7.3.1 Virtual payments

Note that this Payment is permitted to represent a virtual Payment consolidating a number of actual Payments to allow for a wide variety of payment methods. In the case where the Seller is paid monthly, the Payment may refer to a future invoice against which the Payment will eventually be paid.

7.3.2 Basic Payment

A unique reference to this Payment MUST be included in the Payment identifier of the Order sent to the Booking System. This Payment identifier MUST be uniquely resolvable for audit purposes.

The accountId of the Payment SHOULD be provided to reference the specific account within the Payment Provider that is used for reconciliation purposes.

The paymentProviderId of the Payment SHOULD be provided to reference the specific Payment Provider that is used.

The name of the Payment SHOULD be used to provide information about the source of the payment that can be stored in the Booking System, to help the Seller in discussions with the Customer (e.g. "AcmeBroker Points" or "AcmeBroker via Credit Card").

"payment": {
  "type": "Payment",
  "identifier": "12345678ABCD",
  "name": "Big Media Services",
  "accountId": "SN1593",
  "paymentProviderId": "STRIPE"
},

7.3.3 DynamicPayment

For fully dynamic pricing, where price is not known at the point of purchase, a DynamicPayment MUST be used. Example use cases include volume-based pricing, where the price of items are calculated at the end of the month depending on the total volume booked during that period.

To use the DynamicPayment the following preconditions must be met:

• The Broker and the Seller MUST have agreed an arrangement for dynamic pricing out-of-band, including which Opportunities and Offers it applies to.
• Dynamic pricing cannot be mixed with standard pricing behaviour within the same Order, so all OrderItems selected MUST be applicable for dynamic pricing based on such agreements.
• The Opportunities that are selected for booking MUST be bookable as in the standard flow.

To use DynamicPayment the booking flow MUST be completed as normal with the following additional requirements:

• The OrderQuote, OrderProposal and Order in request, response, and in the subsequent Orders feed MUST NOT include totalPaymentDue or totalPaymentTaxSpecification, and OrderItems MUST NOT include acceptedOffer or unitTaxSpecification.
• The booking flow MUST be completed as if prepayment was set to https://openactive.io/Unavailable for the acceptedOffer for all OrderItems.
• The OrderQuote / OrderProposal / Order submitted to C1, C2 and B (and P if using approval) MUST have a payment property that contains a DynamicPayment, which is consistent throughout the calls.
• If the DynamicPayment details supplied (e.g. accountId) are not considered either sufficient or valid for reconciliation by the Booking System then an IncompletePaymentDetailsError or InvalidPaymentDetailsError MUST be returned by all calls, respectively.
• The Booking System MUST NOT record any price against the Order or OrderItems for reconciliation, as such reconciliation MUST occur completely out-of-band.

The accountId of the DynamicPayment MUST be used consistently in order to allow the Seller to reconcile Opportunities booked using a particular account.

The name of the DynamicPayment SHOULD be used to provide information about the source of the payment that can be stored in the Booking System, to help the Seller in discussions with the Customer (e.g. "AcmeBroker Points" or "AcmeBroker Membership").

Note that the Booking System MAY choose to validate the DynamicPayment details, as above, though this is not a requirement - it could simply accept any values provided.

"payment": {
  "type": "DynamicPayment",
  "identifier": "12345678ABCD",
  "name": "MoveGB Membership",
  "accountId": "MOVE"
},

7.3.4 Payment reconciliation

Although automated payment reconciliation is outside the current scope of this specification, a Booking System MAY include identifiers suitable for payment reconciliation to be handled out-of-band with each OrderItem using the additionalProperty property.

In keeping with the Schema.org definition of PropertyValue, the name and value properties MUST be provided within any given PropertyValue, and the Broker SHOULD include these in any reconciliation process with the Seller.

"additionalProperty": [
  {
    "type": "PropertyValue",
    "name": "SiteID",
    "value": "ABC1234"
  },
  {
    "type": "PropertyValue",
    "name": "DeptID",
    "value": "D89"
  }
],

7.4.1 Business-to-consumer tax calculation by Booking System is mandatory

For AgentBroker and NoBroker modes, where the Customer is of type Person and a tax receipt is usually generated by the Booking System, the tax calculation and associated properties this specification MUST be implemented by the Booking System (even if the resulting tax amount is zero).

7.4.2 Business-to-business tax calculation by Booking System is optional

Tax calculation at the Booking System is OPTIONAL when the brokerRole of ResellerBroker is specified, or when a Customer of type Organization is specified. If tax calculation is not supported for a ResellerBroker, unitTaxSpecification and totalPaymentTaxSpecification MUST NOT be included, and the taxCalculationExcluded property MUST be returned as true in the OrderQuote and Order (i.e. explicitly not including tax).

When taxCalculationExcluded is true, all Offers MUST include net prices (i.e. without tax included), regardless of the taxMode. This allows tax to be calculated by the ResellerBroker or business Customer and reconciled outside of this specification.

Note that for business-to-business sales for a Seller with taxMode of the organizer or provider set to https://openactive/TaxGross, the Offers available in the Opportunity Data will still be calculated as tax-inclusive for a business-to-consumer sale, and so MUST be presented by the Broker as such, with the business-to-business tax calculation occurring during the booking flow. If the usecase of presenting the correct price up-front gains traction, additional price data must be made available as part of the openly published Opportunity Data to resolve this shortcoming.

8.1.1 Booking restrictions

Note that although the Customer may be ineligible to attend a bookable Opportunity via an associated bookable Offer based on the genderRestriction or ageRange of either the Opportunity or Offer, this specification encourages the Broker NOT to capture additional personal data about the Customer (e.g. gender and date of birth) and NOT to enforce validation of these restrictions using such data, but instead to prominently communicate clear messaging regarding such restrictions throughout the booking process to ensure that the Customer is aware of these and able to make an informed decision.

There may be additional restrictions placed on an Opportunity by the Seller. For example, it may be that one of the party must be over a certain age as a supervising adult if some of the party are minors. It is the responsibility of the Booking System and Seller to make such restrictions available as attendeeInstructions on the SessionSeries, FacilityUse, Event, HeadlineEvent or CourseInstance, and the Broker MUST communicate these instructions clearly during the booking process.

The Broker MAY filter the Offers it makes available to the Customer, for example based on ageRange of the Offer.

8.3.1 Refund after the opportunity has occurred

Although a cancellation may be requested before the Opportunity has occurred in order to trigger a refund, cancellation and refund after an Opportunity has occurred, or when an OrderItem has orderItemStatus set to https://openactive.io/CustomerAttended, is currently outside the scope of this specification.

Full and partial refunds after an Opportunity has occurred MUST be handled out-of-band directly between the Broker and the Seller.

8.3.2 Customer requested cancellation

To cancel an existing OrderItem, the Broker MUST:

1. Use the latest state of the Order stored during the booking flow and updated via the Orders feed to determine which OrderItems may be cancelled and refunded. If allowCustomerCancellationFullRefund is true and latestCancellationBeforeStartDate subtracted from the Opportunity startDate is in the future, a PATCH against the Order including the OrderItem with "orderItemStatus": "https://openactive.io/CustomerCancelled" SHOULD succeed.

2. Inform the Customer of the refund being requested before they commit to cancellation, using the existing data available in the stored Order to communicate the OrderItems that are included in the full refund request.

3. Submit a PATCH for the Order including only the id for each of the OrderItems to be cancelled, with an "orderItemStatus": "https://openactive.io/CustomerCancelled" set on each. On success, a status code 204 response will be received, without any body. On failure a status code 400 response will be received, containing a CancellationNotPermittedError error including a description of the reason, which SHOULD be communicated to the Customer.

4. Process any refunds based on the resulting updates to the Orders feed, based on the updated totalPaymentDue. Successfully cancelled OrderItems will have orderItemStatus set to https://openactive.io/CustomerCancelled. Note refunds MUST NOT be processed except in response to updates in the Orders feed.

To cancel an entire Order, the PATCH request MUST include "orderItemStatus": "https://openactive.io/CustomerCancelled" for each OrderItem within it.

Note that there is no provision for a Customer to cancel an Order after the cancellation window specified by latestCancellationBeforeStartDate. They may wish to do this out of politeness even though no refund is possible, with the benefit that their place may be taken by another participant, which can be included in future versions of this specification.

8.3.3 Seller requested cancellation

OrderItems cancelled by the Seller will have orderItemStatus set to https://openactive.io/SellerCancelled in the Orders feed, and will optionally include a cancellationMessage. Refunds MUST be processed in response to the resulting updates in the Orders feed, and the Customer MUST be notified with the cancellationMessage if provided.

8.4.1 Orders Feed Inconsistencies

An error condition exists where an unrecognised Order item is found by the Broker on the feed. Due to the Order being stored during the Payment Authorisation stage, there should always be a matching Order to any UUID on the Orders feed even if it has been soft-deleted. This would make an unrecognised Order an impossible scenario, and hence an unrecognised Order should be logged as a serious error within the Broker and promptly investigated.

8.4.2 Order stores with eventual consistency

It is important that the storage used by the Broker for Orders provides a linearizability guarantee when Orders are retrieved by ID, due to the partial updates that are applied to it from the Orders feed and the creation of the initial Order being synchronous.

8.4.3 Booking System: Updating the Orders feed

The Booking System must ensure that the Orders in the Orders feed represent the current state of OrderItems within the system, for the properties included in the feed. Hence any change to any property within an Order in the feed must result in a change to the modified property associated with that Order.

8.4.4 Broker: Processing the Orders feed

The Broker MUST maintain an up-to-date store of Orders received from the Booking System. Each Order received is compared to the last Order stored, and any differences between the old and new content 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 as durable, and not simply a cache, to ensure their Customers always get relevant notifications.

Note 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). 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.

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.

8.4.5 New Orders and OrderProposals

A new Order MUST NOT be communicated externally by the Broker and other operations such as cancellation MUST NOT be possible until it has reached the orderCreationStatus of https://openactive.io/OrderCreationComplete, after which the orderCreationStatus can be completely ignored.

New OrderProposals MUST be stored by the Broker based on a successful response to the Order Proposal call.

New Orders and OrderProposals are not included in the feed until they have been updated at least once. This minimises the volume of Orders in the Orders feed, and allows the polling frequency of the feed to be greatly reduced, which reduces the overall load on the Booking System.

Hence all Orders and OrderProposals in the Orders feed will always be recognised by the Broker as updates to an existing stored Order or OrderProposal, and the Broker should treat any unrecognised Orders or OrderProposals in the feed as a serious implementation error.

8.4.6 Cancellation, refund calculation and notification

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

The Broker MUST process refunds for each new cancellation 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 Orders found with OrderItems that contain orderItemStatus with new https://openactive.io/CustomerCancelled or https://openactive.io/SellerCancelled values and a new corresponding totalPaymentDue value, 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.

The Customer MUST be notified after a refund is successfully processed, using the orderItemStatus to indicate the source of the cancellation.

If refund processing takes longer than 1 minute, and a new status of https://openactive.io/SellerCancelled was detected by the Broker, then the Customer must be notified immediately of a cancellation ahead of the notification of the completed refund. This ensures the Seller can rely on the Broker as a notification channel in the event of cancellation. The Customer MUST be notified with the cancellationMessage for the OrderItem if provided.

Note that the Customer MUST be notified in the event of all cancellations, even if no refund is due for Free Opportunities.

8.4.7 Partial Refunds and out-of-band arrangements

This version of the specification does not allow a refund to be processed (in full or in part) by the Booking System without going via the Broker for any Order that has been placed via the Broker. Booking Systems MUST disable their own refund functionality for Orders placed via a Broker - only allowing Seller requested cancellations which trigger the Broker to provide full item refunds - to ensure that the book keeping and invoices of the Broker are not invalidated.

Partial refunds MAY be handled by out-of-band arrangements between the Broker and the Seller provided they do not have any affect on the Open Booking API interface. For example, the Broker could issue a partial refund and then reassign the remaining funds as a cancellation penalty via a new invoice handled and reconciled directly with the Seller outside the scope of the Booking System and this specification.

8.4.8 Customer notice notifications

The Seller may provide a notice to the Customer ahead of an Opportunity, for example to inform Customers that they are still short of a player in case any friends are interested in attending.

An orderedItem within the OrderItem of the Orders feed MAY be updated to include a customerNotice. The Customer MUST be notified with the contents of the customerNotice for the OrderItem if it differs from the value of customerNotice for that specific orderedItem that the Broker had previously stored (or if a new Order in the Orders feed includes a customerNotice).

Note that notifications that inform the Customer of substantive changes to the Opportunity MUST be triggered by updating the Opportunity Data, which will trigger a Change of logistics notification, instead of using the customerNotice mechanism.

8.4.9 Change of logistics notifications

The orderedItem within the OrderItem of the Orders feed includes an id reference to an Opportunity, which MUST be able to be cross-referenced with other sources of Opportunity Data, for example an [RPDE] open feed.

This specification does not require the Orders feed to include the full contents of the Opportunities within the orderedItem, and hence the Broker MUST monitor the Opportunity Data feeds for this information and MUST provide a notification to the Customer for substantive changes to the Opportunity (e.g. changes to startDate).

Specifically, maximumAttendeeCapacity, remainingAttendeeCapacity, maximumUses and remainingUses MUST NOT be included in the Orders feed.

8.4.10 Opportunity attendance updates

When a Customer has been confirmed as attending an Opportunity that was booked via an Order, the Booking System SHOULD update the Order within the Orders feed by setting orderItemStatus for the relevant OrderItem to https://openactive.io/CustomerAttended.

8.7.1 Text-based access control

PIN codes, Order identifiers, or simply the e-mail address of the Customer are all permissible for the purposes of access control.

In keeping with the Schema.org definition of PropertyValue, the name property SHOULD be used for the name of the property, and the description property SHOULD be used for any human-readable access control code(s).

"accessCode": [
  {
    "type": "PropertyValue",
    "name": "PIN Code",
    "description": "1234"
  }
],

"accessCode": [
  {
    "type": "PropertyValue",
    "name": "Booking Reference",
    "description": "123456789"
  }
],

8.7.2 Image-based access control

Images to be displayed to provide access, for example access tickets rendered by the booking system, MAY be included as an ImageObject within the accessToken array.

ImageObject MUST NOT be used for fallback images of a Barcode; the url property of the Barcode MUST be used for this purpose.

"accessToken": [
  {
    "type": "ImageObject",
    "url": "https://access.example.com/476ac24c694da79c5e33731ebbb5f1"
  }
],

8.7.3 Extension point for barcode-based access control

Access barcodes to be rendered by the Broker MAY be included as a Barcode within the accessToken array. Note that Barcode subclasses ImageObject, allowing it to contain a fallback rendered barcode image url in addition to the raw barcode details. Barcodes SHOULD include a fallback image url.

Due to the variety of barcode formats available, the specification expects the Barcode to include additional properties using a custom namespace (as specified in the [Modelling-Opportunity-Data] specification), enough to allow the barcode to be reproduced by the Broker. This will help inform future versions of the specification.

"accessToken": [
  {
    "type": "Barcode",
    "url": "https://fallback.image.example.com/476ac24c694da79c5e33731ebbb5f1",
    "text": "0123456789",
    "bookwhen:codeType": "code128"
  }
],

9.1.1 Order Endpoint RESTful Semantics

Note that practically all Order endpoints above (those that relate to Order or its subclasses OrderQuote and OrderProposal) share the same UUID namespace, and can be successfully implemented with a single underlying Order record behind them all. These endpoints are distinct purely to reduce the logic required in each and to increase testability and maintainability.

An Order with a particular UUID MUST only exist as either an Order, OrderQuote or OrderProposal at a single point in time.

Hence the Order Status endpoint SHOULD return any stored Order, OrderQuote or OrderProposal with that UUID, and the Orders Feed MUST return both Order and OrderProposal items (noting that OrderQuote are not included in the Orders Feed).

To aid the reader in their semantic reasoning, from a REST perspective, there are four resources:

• /order-quote-templates and /order-quotes - both are a collection resource of OrderQuotes. These are always ephemeral, so are created only for the duration of the PUT request, unless the Booking System chooses to persist them, in which case they exist until the Lease expires or an OrderProposal or Order is created.
• /order-proposals - a collection resource of OrderProposals, which are deleted when a corresponding Order is created.
• /orders - a collection resource of Orders which includes its subclasses OrderQuotes and OrderProposals

9.2.1 OrderQuote Creation C1

The C1 is an endpoint that accepts an OrderQuote without a customer object to check availability and confirm that the specific combination of OrderItems requested can be purchased.

A PUT request to this endpoint of the Booking System with an object of type OrderQuote will return an OrderQuote which represents a "dry run" of the booking, with the state of the Order nearly identical to the result of B (except it excludes customer, attendee, orderItemIntakeFormResponse and the payment identifier), without any side effects (with the exception of optional leasing).

Note that in a simple implementation that does not manage Lease state, attendee details, or additional details, C1 and C2 MAY be exactly the same endpoint that simply validates the email of the customer only if a customer value is supplied. Even for complex implementations, given the similarities between C1 and C2, a single endpoint can used to cover both.

PUT /api/order-quote-templates/e11429ea-467f-4270-ab62-e47368996fe8 HTTP/1.1
Host: example.com
Date: Mon, 8 Oct 2018 20:52:35 GMT
Accept: application/vnd.openactive.booking+json; version=1.0

{
  "@context": "https://openactive.io/",
  "type": "OrderQuote",
  "brokerRole": "https://openactive.io/BrokerAgent",
  "broker": {
    "type": "Organization",
    "name": "MyFitnessApp",
    "url": "https://myfitnessapp.example.com",
    "description": "A fitness app for all the community",
    "logo": {
      "type": "ImageObject",
      "url": "http://data.myfitnessapp.org.uk/images/logo.png"
    },
    "address": {
      "type": "PostalAddress",
      "streetAddress": "Alan Peacock Way",
      "addressLocality": "Village East",
      "addressRegion": "Middlesbrough",
      "postalCode": "TS4 3AE",
      "addressCountry": "GB"
    }
  },
  "orderedItem": [
    {
      "type": "OrderItem",
      "orderQuantity": 1,
      "acceptedOffer": {
        "type": "Offer",
        "id": "https://example.com/events/452#/offers/878"
      },
      "orderedItem": {
        "type": "ScheduledSession",
        "id": "https://example.com/events/452/subEvents/132"
      }
    }
  ]
}

If successful the Booking System will respond with an OrderQuote:

HTTP/1.1 200 OK
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1.0

{
  "@context": "https://openactive.io/",
  "type": "OrderQuote",
  "seller": {
    "type": "Organization",
    "identifier": "CRUOZWJ1",
    "name": "Better",
    "taxMode": "https://openactive/TaxGross",
    "legalName": "Greenwich Leisure Limited",
    "description": "A charitable social enterprise for all the community",
    "url": "https://www.better.org.uk",
    "logo": {
      "type": "ImageObject",
      "url": "http://data.better.org.uk/images/logo.png"
    },
    "telephone": "020 3457 8700",
    "email": "[email protected]",
    "vatID": "GB 789 1234 56",
    "address": {
      "type": "PostalAddress",
      "streetAddress": "Alan Peacock Way",
      "addressLocality": "Village East",
      "addressRegion": "Middlesbrough",
      "postalCode": "TS4 3AE",
      "addressCountry": "GB"
    },
    "termsOfService": [
      {
        "type": "Terms",
        "name": "Privacy Policy",
        "url": "https://example.com/privacy-policy"
      },
      {
        "type": "Terms",
        "name": "Terms and Conditions",
        "url": "https://example.com/terms-and-conditions"
      }
    ]
  },
  "bookingService": {
    "type": "BookingService",
    "name": "Playwaze",
    "url": "http://www.playwaze.com",
    "termsOfService": [
      {
        "type": "Terms",
        "url": "https://brokerexample.com/terms.html"
      }
    ]
  },
  "lease": {
    "type": "Lease",
    "leaseExpires": "2018-10-01T11:00:00Z"
  },
  "orderedItem": [
    {
      "type": "OrderItem",
      "orderQuantity": 1,
      "orderItemStatus": "https://openactive.io/OrderConfirmed",
      "allowCustomerCancellationFullRefund": true,
      "unitTaxSpecification": [
        {
          "type": "TaxChargeSpecification",
          "name": "VAT at 0% for EU transactions",
          "price": 1,
          "priceCurrency": "GBP",
          "rate": 0.2
        }
      ],
      "acceptedOffer": {
        "type": "Offer",
        "id": "https://example.com/events/452#/offers/878",
        "description": "Winger space for Speedball.",
        "name": "Speedball winger position",
        "price": 10,
        "priceCurrency": "GBP",
        "validFromBeforeStartDate": "P6D",
        "latestCancellationBeforeStartDate": "P1D"
      },
      "orderedItem": {
        "type": "ScheduledSession",
        "identifier": 123,
        "id": "https://example.com/events/452/subEvents/132",
        "eventStatus": "https://schema.org/EventScheduled",
        "maximumAttendeeCapacity": 30,
        "remainingAttendeeCapacity": 20,
        "startDate": "2018-10-30T11:00:00Z",
        "endDate": "2018-10-30T12:00:00Z",
        "duration": "PT1H",
        "superEvent": {
          "type": "SessionSeries",
          "id": "https://example.com/events/452",
          "name": "Speedball",
          "duration": "PT1H",
          "organizer": {
            "type": "Organization",
            "name": "Central Speedball Association",
            "url": "http://www.speedball-world.com"
          },
          "location": {
            "type": "Place",
            "url": "https://www.everyoneactive.com/centres/Middlesbrough-Sports-Village",
            "name": "Middlesbrough Sports Village",
            "identifier": "0140",
            "address": {
              "type": "PostalAddress",
              "streetAddress": "Alan Peacock Way",
              "addressLocality": "Village East",
              "addressRegion": "Middlesbrough",
              "postalCode": "TS4 3AE",
              "addressCountry": "GB"
            },
            "geo": {
              "type": "GeoCoordinates",
              "latitude": 54.543964,
              "longitude": -1.20978500000001
            }
          }
        }
      }
    }
  ],
  "totalPaymentDue": {
    "type": "PriceSpecification",
    "price": 5,
    "priceCurrency": "GBP"
  },
  "totalTaxSpecification": [
    {
      "type": "TaxChargeSpecification",
      "name": "VAT at 20%",
      "price": 1,
      "priceCurrency": "GBP",
      "rate": 0.2
    }
  ]
}

If there are any issues with the OrderItems requested in the OrderQuote, the Booking System MUST respond with a 409 Conflict response (as the error is expected to be resolved, and the request resubmitted, as per [RFC2616]), with error details provided against each offending OrderItem. Note that totalPaymentDue and totalPaymentTaxSpecification MUST be calculated excluding any OrderItems that include errors.

HTTP/1.1 409 Conflict
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1.0

{
  "@context": "https://openactive.io/",
  "type": "OrderQuote",
  "seller": {
    "type": "Organization",
    "identifier": "CRUOZWJ1",
    "name": "Better",
    "taxMode": "https://openactive/TaxGross",
    "legalName": "Greenwich Leisure Limited",
    "description": "A charitable social enterprise for all the community",
    "url": "https://www.better.org.uk",
    "logo": {
      "type": "ImageObject",
      "url": "http://data.better.org.uk/images/logo.png"
    },
    "telephone": "020 3457 8700",
    "email": "[email protected]",
    "vatID": "GB 789 1234 56",
    "address": {
      "type": "PostalAddress",
      "streetAddress": "Alan Peacock Way",
      "addressLocality": "Village East",
      "addressRegion": "Middlesbrough",
      "postalCode": "TS4 3AE",
      "addressCountry": "GB"
    },
    "termsOfService": [
      {
        "type": "Terms",
        "name": "Privacy Policy",
        "url": "https://example.com/privacy-policy"
      },
      {
        "type": "Terms",
        "name": "Terms and Conditions",
        "url": "https://example.com/terms-and-conditions"
      }
    ]
  },
  "bookingService": {
    "type": "BookingService",
    "name": "Playwaze",
    "url": "http://www.playwaze.com",
    "termsOfService": [
      {
        "type": "Terms",
        "url": "https://brokerexample.com/terms.html"
      }
    ]
  },
  "lease": {
    "type": "Lease",
    "leaseExpires": "2018-10-01T11:00:00Z"
  },
  "orderedItem": [
    {
      "type": "OrderItem",
      "orderQuantity": 1,
      "orderItemStatus": "https://openactive.io/OrderConfirmed",
      "allowCustomerCancellationFullRefund": true,
      "unitTaxSpecification": [
        {
          "type": "TaxChargeSpecification",
          "name": "VAT at 0% for EU transactions",
          "price": 1,
          "priceCurrency": "GBP",
          "rate": 0.2
        }
      ],
      "acceptedOffer": {
        "type": "Offer",
        "id": "https://example.com/events/452#/offers/878",
        "description": "Winger space for Speedball.",
        "name": "Speedball winger position",
        "price": 10,
        "priceCurrency": "GBP",
        "validFromBeforeStartDate": "P6D",
        "latestCancellationBeforeStartDate": "P1D"
      },
      "orderedItem": {
        "type": "ScheduledSession",
        "identifier": 123,
        "id": "https://example.com/events/452/subEvents/132",
        "eventStatus": "https://schema.org/EventScheduled",
        "maximumAttendeeCapacity": 30,
        "remainingAttendeeCapacity": 20,
        "startDate": "2018-10-30T11:00:00Z",
        "endDate": "2018-10-30T12:00:00Z",
        "duration": "PT1H",
        "superEvent": {
          "type": "SessionSeries",
          "id": "https://example.com/events/452",
          "name": "Speedball",
          "duration": "PT1H",
          "organizer": {
            "type": "Organization",
            "name": "Central Speedball Association",
            "url": "http://www.speedball-world.com"
          },
          "location": {
            "type": "Place",
            "url": "https://www.everyoneactive.com/centres/Middlesbrough-Sports-Village",
            "name": "Middlesbrough Sports Village",
            "identifier": "0140",
            "address": {
              "type": "PostalAddress",
              "streetAddress": "Alan Peacock Way",
              "addressLocality": "Village East",
              "addressRegion": "Middlesbrough",
              "postalCode": "TS4 3AE",
              "addressCountry": "GB"
            },
            "geo": {
              "type": "GeoCoordinates",
              "latitude": 54.543964,
              "longitude": -1.20978500000001
            }
          }
        }
      },
      "error": [
        {
          "type": "OpportunityIsFullError",
          "description": "There are no spaces remaining in this opportunity"
        }
      ]
    }
  ],
  "totalPaymentDue": {
    "type": "PriceSpecification",
    "price": 0,
    "priceCurrency": "GBP"
  },
  "totalTaxSpecification": [
    {
      "type": "TaxChargeSpecification",
      "name": "VAT at 20%",
      "price": 0,
      "priceCurrency": "GBP",
      "rate": 0.2
    }
  ]
}

If there are issues with other properties of the OrderQuote outside of orderedItem, the Booking System MUST respond with a JSON-LD response which includes only the appropriate OpenBookingError and the appropriate status code.

HTTP/1.1 500 Internal Server Error
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1.0

{
  "@context": "https://openactive.io/",
  "type": "TemporarilyUnableToProduceOrderQuoteError",
  "description": "Temporary error occurred in the database"
}

9.2.2 OrderQuote Creation C2

The C2 is PUT endpoint that accepts an OrderQuote with a customer object to check availability and confirm that the specific combination of OrderItems requested can be purchased.

A PUT request to this endpoint of the Booking System with an object of type OrderQuote will return an OrderQuote which represents a "dry run" of the booking, with the state of the Order nearly identical to the result of B (except it excludes payment identifier), without any side effects (with the exception of optional leasing).

Note that the Booking System MUST NOT store any personal information of the customer provided for the OrderQuote past the expiry of any associated Lease created.

PUT /api/order-quotes/e11429ea-467f-4270-ab62-e47368996fe8 HTTP/1.1
Host: example.com
Date: Mon, 8 Oct 2018 20:52:35 GMT
Accept: application/vnd.openactive.booking+json; version=1.0

{
  "@context": "https://openactive.io/",
  "type": "OrderQuote",
  "brokerRole": "https://openactive.io/BrokerAgent",
  "broker": {
    "type": "Organization",
    "name": "MyFitnessApp",
    "url": "https://myfitnessapp.example.com",
    "description": "A fitness app for all the community",
    "logo": {
      "type": "ImageObject",
      "url": "http://data.myfitnessapp.org.uk/images/logo.png"
    },
    "address": {
      "type": "PostalAddress",
      "streetAddress": "Alan Peacock Way",
      "addressLocality": "Village East",
      "addressRegion": "Middlesbrough",
      "postalCode": "TS4 3AE",
      "addressCountry": "GB"
    }
  },
  "customer": {
    "type": "Person",
    "email": "[email protected]",
    "telephone": "020 811 8055",
    "givenName": "Geoff",
    "familyName": "Capes"
  },
  "orderedItem": [
    {
      "type": "OrderItem",
      "orderQuantity": 1,
      "acceptedOffer": {
        "type": "Offer",
        "id": "https://example.com/events/452#/offers/878"
      },
      "orderedItem": {
        "type": "ScheduledSession",
        "id": "https://example.com/events/452/subEvents/132"
      }
    }
  ]
}

If successful the Booking System will respond with an OrderQuote:

HTTP/1.1 200 OK
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1.0

{
  "@context": "https://openactive.io/",
  "type": "OrderQuote",
  "seller": {
    "type": "Organization",
    "identifier": "CRUOZWJ1",
    "name": "Better",
    "taxMode": "https://openactive/TaxGross",
    "legalName": "Greenwich Leisure Limited",
    "description": "A charitable social enterprise for all the community",
    "url": "https://www.better.org.uk",
    "logo": {
      "type": "ImageObject",
      "url": "http://data.better.org.uk/images/logo.png"
    },
    "telephone": "020 3457 8700",
    "email": "[email protected]",
    "vatID": "GB 789 1234 56",
    "address": {
      "type": "PostalAddress",
      "streetAddress": "Alan Peacock Way",
      "addressLocality": "Village East",
      "addressRegion": "Middlesbrough",
      "postalCode": "TS4 3AE",
      "addressCountry": "GB"
    },
    "termsOfService": [
      {
        "type": "Terms",
        "name": "Privacy Policy",
        "url": "https://example.com/privacy-policy"
      },
      {
        "type": "Terms",
        "name": "Terms and Conditions",
        "url": "https://example.com/terms-and-conditions"
      }
    ]
  },
  "customer": {
    "type": "Person",
    "email": "[email protected]",
    "telephone": "020 811 8055",
    "givenName": "Geoff",
    "familyName": "Capes"
  },
  "bookingService": {
    "type": "BookingService",
    "name": "Playwaze",
    "url": "http://www.playwaze.com",
    "termsOfService": [
      {
        "type": "Terms",
        "url": "https://brokerexample.com/terms.html"
      }
    ]
  },
  "lease": {
    "type": "Lease",
    "leaseExpires": "2018-10-01T11:00:00Z"
  },
  "orderedItem": [
    {
      "type": "OrderItem",
      "orderQuantity": 1,
      "orderItemStatus": "https://openactive.io/OrderConfirmed",
      "allowCustomerCancellationFullRefund": true,
      "unitTaxSpecification": [
        {
          "type": "TaxChargeSpecification",
          "name": "VAT at 0% for EU transactions",
          "price": 1,
          "priceCurrency": "GBP",
          "rate": 0.2
        }
      ],
      "acceptedOffer": {
        "type": "Offer",
        "id": "https://example.com/events/452#/offers/878",
        "description": "Winger space for Speedball.",
        "name": "Speedball winger position",
        "price": 10,
        "priceCurrency": "GBP",
        "validFromBeforeStartDate": "P6D",
        "latestCancellationBeforeStartDate": "P1D"
      },
      "orderedItem": {
        "type": "ScheduledSession",
        "identifier": 123,
        "id": "https://example.com/events/452/subEvents/132",
        "eventStatus": "https://schema.org/EventScheduled",
        "maximumAttendeeCapacity": 30,
        "remainingAttendeeCapacity": 20,
        "startDate": "2018-10-30T11:00:00Z",
        "endDate": "2018-10-30T12:00:00Z",
        "duration": "PT1H",
        "superEvent": {
          "type": "SessionSeries",
          "id": "https://example.com/events/452",
          "name": "Speedball",
          "duration": "PT1H",
          "organizer": {
            "type": "Organization",
            "name": "Central Speedball Association",
            "url": "http://www.speedball-world.com"
          },
          "location": {
            "type": "Place",
            "url": "https://www.everyoneactive.com/centres/Middlesbrough-Sports-Village",
            "name": "Middlesbrough Sports Village",
            "identifier": "0140",
            "address": {
              "type": "PostalAddress",
              "streetAddress": "Alan Peacock Way",
              "addressLocality": "Village East",
              "addressRegion": "Middlesbrough",
              "postalCode": "TS4 3AE",
              "addressCountry": "GB"
            },
            "geo": {
              "type": "GeoCoordinates",
              "latitude": 54.543964,
              "longitude": -1.20978500000001
            }
          }
        }
      }
    }
  ],
  "totalPaymentDue": {
    "type": "PriceSpecification",
    "price": 5,
    "priceCurrency": "GBP"
  },
  "totalTaxSpecification": [
    {
      "type": "TaxChargeSpecification",
      "name": "VAT at 20%",
      "price": 1,
      "priceCurrency": "GBP",
      "rate": 0.2
    }
  ]
}

Note if the response includes orderRequiresApproval with a value of true the Broker MUST make it clear to the Customer of the additional process they are about to enter into, and once they are aware, move forward according to the Booking Flow with Approval rather than the Simple Booking Flow.

If there are any issues with the OrderItems requested in the OrderQuote, the Booking System MUST respond with a 409 Conflict response (as the error is expected to be resolved, and the request resubmitted, as per [RFC2616]), with error details provided against each offending OrderItem. Note that totalPaymentDue and totalPaymentTaxSpecification MUST be calculated excluding any OrderItems that include errors.

HTTP/1.1 409 Conflict
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1.0

{
  "@context": "https://openactive.io/",
  "type": "OrderQuote",
  "seller": {
    "type": "Organization",
    "identifier": "CRUOZWJ1",
    "name": "Better",
    "taxMode": "https://openactive/TaxGross",
    "legalName": "Greenwich Leisure Limited",
    "description": "A charitable social enterprise for all the community",
    "url": "https://www.better.org.uk",
    "logo": {
      "type": "ImageObject",
      "url": "http://data.better.org.uk/images/logo.png"
    },
    "telephone": "020 3457 8700",
    "email": "[email protected]",
    "vatID": "GB 789 1234 56",
    "address": {
      "type": "PostalAddress",
      "streetAddress": "Alan Peacock Way",
      "addressLocality": "Village East",
      "addressRegion": "Middlesbrough",
      "postalCode": "TS4 3AE",
      "addressCountry": "GB"
    },
    "termsOfService": [
      {
        "type": "Terms",
        "name": "Privacy Policy",
        "url": "https://example.com/privacy-policy"
      },
      {
        "type": "Terms",
        "name": "Terms and Conditions",
        "url": "https://example.com/terms-and-conditions"
      }
    ]
  },
  "customer": {
    "type": "Person",
    "email": "[email protected]",
    "telephone": "020 811 8055",
    "givenName": "Geoff",
    "familyName": "Capes"
  },
  "bookingService": {
    "type": "BookingService",
    "name": "Playwaze",
    "url": "http://www.playwaze.com",
    "termsOfService": [
      {
        "type": "Terms",
        "url": "https://brokerexample.com/terms.html"
      }
    ]
  },
  "lease": {
    "type": "Lease",
    "leaseExpires": "2018-10-01T11:00:00Z"
  },
  "orderedItem": [
    {
      "type": "OrderItem",
      "orderQuantity": 1,
      "orderItemStatus": "https://openactive.io/OrderConfirmed",
      "allowCustomerCancellationFullRefund": true,
      "unitTaxSpecification": [
        {
          "type": "TaxChargeSpecification",
          "name": "VAT at 0% for EU transactions",
          "price": 1,
          "priceCurrency": "GBP",
          "rate": 0.2
        }
      ],
      "acceptedOffer": {
        "type": "Offer",
        "id": "https://example.com/events/452#/offers/878",
        "description": "Winger space for Speedball.",
        "name": "Speedball winger position",
        "price": 10,
        "priceCurrency": "GBP",
        "validFromBeforeStartDate": "P6D",
        "latestCancellationBeforeStartDate": "P1D"
      },
      "orderedItem": {
        "type": "ScheduledSession",
        "identifier": 123,
        "id": "https://example.com/events/452/subEvents/132",
        "eventStatus": "https://schema.org/EventScheduled",
        "maximumAttendeeCapacity": 30,
        "remainingAttendeeCapacity": 20,
        "startDate": "2018-10-30T11:00:00Z",
        "endDate": "2018-10-30T12:00:00Z",
        "duration": "PT1H",
        "superEvent": {
          "type": "SessionSeries",
          "id": "https://example.com/events/452",
          "name": "Speedball",
          "duration": "PT1H",
          "organizer": {
            "type": "Organization",
            "name": "Central Speedball Association",
            "url": "http://www.speedball-world.com"
          },
          "location": {
            "type": "Place",
            "url": "https://www.everyoneactive.com/centres/Middlesbrough-Sports-Village",
            "name": "Middlesbrough Sports Village",
            "identifier": "0140",
            "address": {
              "type": "PostalAddress",
              "streetAddress": "Alan Peacock Way",
              "addressLocality": "Village East",
              "addressRegion": "Middlesbrough",
              "postalCode": "TS4 3AE",
              "addressCountry": "GB"
            },
            "geo": {
              "type": "GeoCoordinates",
              "latitude": 54.543964,
              "longitude": -1.20978500000001
            }
          }
        }
      },
      "error": [
        {
          "type": "OpportunityIsFullError",
          "description": "There are no spaces remaining in this opportunity"
        }
      ]
    }
  ],
  "totalPaymentDue": {
    "type": "PriceSpecification",
    "price": 0,
    "priceCurrency": "GBP"
  },
  "totalTaxSpecification": [
    {
      "type": "TaxChargeSpecification",
      "name": "VAT at 20%",
      "price": 0,
      "priceCurrency": "GBP",
      "rate": 0.2
    }
  ]
}

If there are issues with other properties of the OrderQuote outside of orderedItem, the Booking System MUST respond with a JSON-LD response which includes only the appropriate OpenBookingError and the appropriate status code.

HTTP/1.1 500 Internal Server Error
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1.0

{
  "@context": "https://openactive.io/",
  "type": "TemporarilyUnableToProduceOrderQuoteError",
  "description": "Temporary error occurred in the database"
}

9.2.3 OrderQuote Deletion

Deleting an OrderQuote releases any Lease associated with it, which the Broker SHOULD do as a courtesy if the Customer has abandoned their journey. An OrderQuote Deletion request MUST simply return a 204 success status in all cases (including cases where the Booking Systems has not implemented leasing), as the OrderQuote itself is ephemeral.

DELETE /api/orders/e11429ea-467f-4270-ab62-e47368996fe8 HTTP/1.1
Host: example.com
Date: Mon, 8 Oct 2018 20:52:35 GMT
Accept: application/vnd.openactive.booking+json; version=1.0

HTTP/1.1 204 No Content
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1.0

9.2.4 OrderProposal Creation P

P is a PUT endpoint that creates and returns the submitted OrderProposal with an orderProposalStatus of https://openactive.io/AwaitingSellerConfirmation. The details submitted are identical to those required for B with the addition of an optional lease.

PUT /api/order-proposals/e11429ea-467f-4270-ab62-e47368996fe8 HTTP/1.1
Host: example.com
Date: Mon, 8 Oct 2018 20:52:35 GMT
Accept: application/vnd.openactive.booking+json; version=1.0

{
  "@context": "https://openactive.io/",
  "type": "OrderProposal",
  "brokerRole": "https://openactive.io/BrokerAgent",
  "broker": {
    "type": "Organization",
    "name": "MyFitnessApp",
    "url": "https://myfitnessapp.example.com",
    "description": "A fitness app for all the community",
    "logo": {
      "type": "ImageObject",
      "url": "http://data.myfitnessapp.org.uk/images/logo.png"
    },
    "address": {
      "type": "PostalAddress",
      "streetAddress": "Alan Peacock Way",
      "addressLocality": "Village East",
      "addressRegion": "Middlesbrough",
      "postalCode": "TS4 3AE",
      "addressCountry": "GB"
    }
  },
  "customer": {
    "type": "Person",
    "email": "[email protected]",
    "telephone": "020 811 8055",
    "givenName": "Geoff",
    "familyName": "Capes"
  },
  "orderedItem": [
    {
      "type": "OrderItem",
      "orderQuantity": 1,
      "acceptedOffer": {
        "type": "Offer",
        "id": "https://example.com/events/452#/offers/878"
      },
      "orderedItem": {
        "type": "ScheduledSession",
        "id": "https://example.com/events/452/subEvents/132"
      }
    }
  ],
  "totalPaymentDue": {
    "type": "PriceSpecification",
    "price": 5,
    "priceCurrency": "GBP"
  },
  "payment": {
    "type": "Payment",
    "name": "AcmeBroker Points",
    "identifier": "1234567890npduy2f"
  }
}

If successful the Booking System will respond with an OrderProposal:

HTTP/1.1 201 Created
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1.0
Location: /api/order-proposals/e11429ea-467f-4270-ab62-e47368996fe8

{
  "@context": "https://openactive.io/",
  "type": "OrderProposal",
  "id": "https://example.com/api/orders/e11429ea-467f-4270-ab62-e47368996fe8",
  "orderNumber": "AB000001",
  "orderProposalVersion": "https://api.example.com/order-proposals/358105b4-e571-43fa-b737-906d319c6a32/version/8eb1a6ce-3f5b-40b0-87a7-bddb4c5518bd",
  "brokerRole": "https://openactive.io/BrokerAgent",
  "broker": {
    "type": "Organization",
    "name": "MyFitnessApp",
    "url": "https://myfitnessapp.example.com",
    "description": "A fitness app for all the community",
    "logo": {
      "type": "ImageObject",
      "url": "http://data.myfitnessapp.org.uk/images/logo.png"
    },
    "address": {
      "type": "PostalAddress",
      "streetAddress": "Alan Peacock Way",
      "addressLocality": "Village East",
      "addressRegion": "Middlesbrough",
      "postalCode": "TS4 3AE",
      "addressCountry": "GB"
    }
  },
  "customer": {
    "type": "Person",
    "email": "[email protected]",
    "telephone": "020 811 8055",
    "givenName": "Geoff",
    "familyName": "Capes"
  },
  "seller": {
    "type": "Organization",
    "identifier": "CRUOZWJ1",
    "name": "Better",
    "taxMode": "https://openactive/TaxGross",
    "legalName": "Greenwich Leisure Limited",
    "description": "A charitable social enterprise for all the community",
    "url": "https://www.better.org.uk",
    "logo": {
      "type": "ImageObject",
      "url": "http://data.better.org.uk/images/logo.png"
    },
    "telephone": "020 3457 8700",
    "email": "[email protected]",
    "vatID": "GB 789 1234 56",
    "address": {
      "type": "PostalAddress",
      "streetAddress": "Alan Peacock Way",
      "addressLocality": "Village East",
      "addressRegion": "Middlesbrough",
      "postalCode": "TS4 3AE",
      "addressCountry": "GB"
    },
    "termsOfService": [
      {
        "type": "Terms",
        "name": "Privacy Policy",
        "url": "https://example.com/privacy-policy"
      },
      {
        "type": "Terms",
        "name": "Terms and Conditions",
        "url": "https://example.com/terms-and-conditions"
      }
    ]
  },
  "bookingService": {
    "type": "BookingService",
    "name": "Playwaze",
    "url": "http://www.playwaze.com",
    "termsOfService": [
      {
        "type": "Terms",
        "url": "https://brokerexample.com/terms.html"
      }
    ]
  },
  "orderedItem": [
    {
      "type": "OrderItem",
      "id": "https://example.com/api/orders/123e4567-e89b-12d3-a456-426655440000/order-items/1234",
      "orderItemStatus": "https://openactive.io/OrderConfirmed",
      "allowCustomerCancellationFullRefund": true,
      "unitTaxSpecification": [
        {
          "type": "TaxChargeSpecification",
          "name": "VAT at 0% for EU transactions",
          "price": 1,
          "priceCurrency": "GBP",
          "rate": 0.2
        }
      ],
      "acceptedOffer": {
        "type": "Offer",
        "id": "https://example.com/events/452#/offers/878",
        "description": "Winger space for Speedball.",
        "name": "Speedball winger position",
        "price": 10,
        "priceCurrency": "GBP",
        "validFromBeforeStartDate": "P6D",
        "latestCancellationBeforeStartDate": "P1D"
      },
      "orderedItem": {
        "type": "ScheduledSession",
        "identifier": 123,
        "id": "https://example.com/events/452/subEvents/132",
        "eventStatus": "https://schema.org/EventScheduled",
        "startDate": "2018-10-30T11:00:00Z",
        "endDate": "2018-10-30T12:00:00Z",
        "duration": "PT1H",
        "superEvent": {
          "type": "SessionSeries",
          "id": "https://example.com/events/452",
          "name": "Speedball",
          "organizer": {
            "type": "Organization",
            "name": "Central Speedball Association",
            "url": "http://www.speedball-world.com"
          },
          "location": {
            "type": "Place",
            "url": "https://www.everyoneactive.com/centres/Middlesbrough-Sports-Village",
            "name": "Middlesbrough Sports Village",
            "identifier": "0140",
            "address": {
              "type": "PostalAddress",
              "streetAddress": "Alan Peacock Way",
              "addressLocality": "Village East",
              "addressRegion": "Middlesbrough",
              "postalCode": "TS4 3AE",
              "addressCountry": "GB"
            },
            "geo": {
              "type": "GeoCoordinates",
              "latitude": 54.543964,
              "longitude": -1.20978500000001
            }
          }
        }
      },
      "accessToken": [
        {
          "type": "Barcode",
          "text": "0123456789"
        }
      ]
    }
  ],
  "totalPaymentDue": {
    "type": "PriceSpecification",
    "price": 5,
    "priceCurrency": "GBP"
  },
  "totalTaxSpecification": [
    {
      "type": "TaxChargeSpecification",
      "name": "VAT at 20%",
      "price": 1,
      "priceCurrency": "GBP",
      "rate": 0.2
    }
  ],
  "payment": {
    "type": "Payment",
    "name": "AcmeBroker Points",
    "identifier": "1234567890npduy2f"
  },
  "lease": {
    "type": "Lease",
    "leaseExpires": "2018-10-01T11:00:00Z"
  }
}

If there are issues with any properties of the OrderProposal, including the orderedItem, the Booking System MUST respond with an error response which includes only the appropriate OpenBookingError and the appropriate status code. The Broker is expected to retry the OrderQuote to get specific orderedItem level errors.

HTTP/1.1 400 Bad Request
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1.0

{
  "@context": "https://openactive.io/",
  "type": "IncompleteBrokerDetailsError",
  "description": "Only 'https://openactive.io/CustomerRejected' is permitted for this property."
}

Note that any validation errors raised at P regarding any property values MUST also be raised at C2 (and ideally also C1 if relevant), so it should be very unusual to receive an error at P.

9.2.5 OrderProposal Update

The endpoint accepts a simple PATCH containing either or both of orderProposalStatus and orderCustomerNote.

PATCH /api/order-proposals/e11429ea-467f-4270-ab62-e47368996fe8 HTTP/1.1
Host: example.com
Date: Mon, 8 Oct 2018 20:52:35 GMT
Accept: application/vnd.openactive.booking+json; version=1.0

{
  "@context": "https://openactive.io/",
  "type": "OrderProposal",
  "orderProposalStatus": "https://openactive.io/CustomerRejected",
  "orderCustomerNote": "Sorry I've actually made other plans, hope you find someone!"
}

HTTP/1.1 204 No Content
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1.0

A PATCH to update orderProposalStatus MUST have the value https://openactive.io/CustomerRejected, as that is the only permissible value based on the logic defined in this version of the specification. If another value for orderProposalStatus is specified the endpoint MUST return an PatchNotAllowedOnProperty error with its status code.

HTTP/1.1 400 Bad Request
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1.0

{
  "@context": "https://openactive.io/",
  "type": "PatchNotAllowedOnProperty",
  "instance": "https://openactive.io/orderProposalStatus",
  "description": "Only 'https://openactive.io/CustomerRejected' is permitted for this property."
}

If the PATCH request includes any properties other than type, @context, orderProposalStatus and orderCustomerNote (excluding any properties with a custom namespace), the endpoint MUST return a PatchContainsExcessiveProperties error with its status code.

HTTP/1.1 400 Bad Request
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1.0

{
  "@context": "https://openactive.io/",
  "type": "PatchContainsExcessiveProperties",
  "description": "PATCH includes unexpected properties that are not permitted."
}

9.2.6 Order Creation B

A PUT request to the Order Creation endpoint of the Booking System with an object of type Order will create the Order and complete the booking from the point of the view of the Booking System.

PUT /api/orders/e11429ea-467f-4270-ab62-e47368996fe8 HTTP/1.1
Host: example.com
Date: Mon, 8 Oct 2018 20:52:35 GMT
Accept: application/vnd.openactive.booking+json; version=1.0

{
  "@context": "https://openactive.io/",
  "type": "Order",
  "brokerRole": "https://openactive.io/BrokerAgent",
  "broker": {
    "type": "Organization",
    "name": "MyFitnessApp",
    "url": "https://myfitnessapp.example.com",
    "description": "A fitness app for all the community",
    "logo": {
      "type": "ImageObject",
      "url": "http://data.myfitnessapp.org.uk/images/logo.png"
    },
    "address": {
      "type": "PostalAddress",
      "streetAddress": "Alan Peacock Way",
      "addressLocality": "Village East",
      "addressRegion": "Middlesbrough",
      "postalCode": "TS4 3AE",
      "addressCountry": "GB"
    }
  },
  "customer": {
    "type": "Person",
    "email": "[email protected]",
    "telephone": "020 811 8055",
    "givenName": "Geoff",
    "familyName": "Capes"
  },
  "orderedItem": [
    {
      "type": "OrderItem",
      "orderQuantity": 1,
      "acceptedOffer": {
        "type": "Offer",
        "id": "https://example.com/events/452#/offers/878"
      },
      "orderedItem": {
        "type": "ScheduledSession",
        "id": "https://example.com/events/452/subEvents/132"
      }
    }
  ],
  "totalPaymentDue": {
    "type": "PriceSpecification",
    "price": 5,
    "priceCurrency": "GBP"
  },
  "payment": {
    "type": "Payment",
    "name": "AcmeBroker Points",
    "identifier": "1234567890npduy2f"
  }
}

If successful the server will respond with the location of a newly created Order resource.

For the Order response and the Orders feed, the OrderItems MUST include a unique id. This allows OrderItems to be referenced in subsequent PATCH calls once the Order has been created.

B responses MUST reflect back properties provided by the Booking System, for example:

HTTP/1.1 201 Created
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1.0
Location: /api/orders/e11429ea-467f-4270-ab62-e47368996fe8

{
  "@context": "https://openactive.io/",
  "type": "Order",
  "id": "https://example.com/api/orders/e11429ea-467f-4270-ab62-e47368996fe8",
  "orderNumber": "AB000001",
  "brokerRole": "https://openactive.io/BrokerAgent",
  "broker": {
    "type": "Organization",
    "name": "MyFitnessApp",
    "url": "https://myfitnessapp.example.com",
    "description": "A fitness app for all the community",
    "logo": {
      "type": "ImageObject",
      "url": "http://data.myfitnessapp.org.uk/images/logo.png"
    },
    "address": {
      "type": "PostalAddress",
      "streetAddress": "Alan Peacock Way",
      "addressLocality": "Village East",
      "addressRegion": "Middlesbrough",
      "postalCode": "TS4 3AE",
      "addressCountry": "GB"
    }
  },
  "customer": {
    "type": "Person",
    "email": "[email protected]",
    "telephone": "020 811 8055",
    "givenName": "Geoff",
    "familyName": "Capes"
  },
  "seller": {
    "type": "Organization",
    "identifier": "CRUOZWJ1",
    "name": "Better",
    "taxMode": "https://openactive/TaxGross",
    "legalName": "Greenwich Leisure Limited",
    "description": "A charitable social enterprise for all the community",
    "url": "https://www.better.org.uk",
    "logo": {
      "type": "ImageObject",
      "url": "http://data.better.org.uk/images/logo.png"
    },
    "telephone": "020 3457 8700",
    "email": "[email protected]",
    "vatID": "GB 789 1234 56",
    "address": {
      "type": "PostalAddress",
      "streetAddress": "Alan Peacock Way",
      "addressLocality": "Village East",
      "addressRegion": "Middlesbrough",
      "postalCode": "TS4 3AE",
      "addressCountry": "GB"
    },
    "termsOfService": [
      {
        "type": "Terms",
        "name": "Privacy Policy",
        "url": "https://example.com/privacy-policy"
      },
      {
        "type": "Terms",
        "name": "Terms and Conditions",
        "url": "https://example.com/terms-and-conditions"
      }
    ]
  },
  "bookingService": {
    "type": "BookingService",
    "name": "Playwaze",
    "url": "http://www.playwaze.com",
    "termsOfService": [
      {
        "type": "Terms",
        "url": "https://brokerexample.com/terms.html"
      }
    ]
  },
  "orderedItem": [
    {
      "type": "OrderItem",
      "id": "https://example.com/api/orders/123e4567-e89b-12d3-a456-426655440000/order-items/1234",
      "orderItemStatus": "https://openactive.io/OrderConfirmed",
      "allowCustomerCancellationFullRefund": true,
      "unitTaxSpecification": [
        {
          "type": "TaxChargeSpecification",
          "name": "VAT at 0% for EU transactions",
          "price": 1,
          "priceCurrency": "GBP",
          "rate": 0.2
        }
      ],
      "acceptedOffer": {
        "type": "Offer",
        "id": "https://example.com/events/452#/offers/878",
        "description": "Winger space for Speedball.",
        "name": "Speedball winger position",
        "price": 10,
        "priceCurrency": "GBP",
        "validFromBeforeStartDate": "P6D",
        "latestCancellationBeforeStartDate": "P1D"
      },
      "orderedItem": {
        "type": "ScheduledSession",
        "identifier": 123,
        "id": "https://example.com/events/452/subEvents/132",
        "eventStatus": "https://schema.org/EventScheduled",
        "startDate": "2018-10-30T11:00:00Z",
        "endDate": "2018-10-30T12:00:00Z",
        "duration": "PT1H",
        "superEvent": {
          "type": "SessionSeries",
          "id": "https://example.com/events/452",
          "name": "Speedball",
          "organizer": {
            "type": "Organization",
            "name": "Central Speedball Association",
            "url": "http://www.speedball-world.com"
          },
          "location": {
            "type": "Place",
            "url": "https://www.everyoneactive.com/centres/Middlesbrough-Sports-Village",
            "name": "Middlesbrough Sports Village",
            "identifier": "0140",
            "address": {
              "type": "PostalAddress",
              "streetAddress": "Alan Peacock Way",
              "addressLocality": "Village East",
              "addressRegion": "Middlesbrough",
              "postalCode": "TS4 3AE",
              "addressCountry": "GB"
            },
            "geo": {
              "type": "GeoCoordinates",
              "latitude": 54.543964,
              "longitude": -1.20978500000001
            }
          }
        }
      },
      "accessToken": [
        {
          "type": "Barcode",
          "text": "0123456789"
        }
      ]
    }
  ],
  "totalPaymentDue": {
    "type": "PriceSpecification",
    "price": 5,
    "priceCurrency": "GBP"
  },
  "totalTaxSpecification": [
    {
      "type": "TaxChargeSpecification",
      "name": "VAT at 20%",
      "price": 1,
      "priceCurrency": "GBP",
      "rate": 0.2
    }
  ],
  "payment": {
    "type": "Payment",
    "name": "AcmeBroker Points",
    "identifier": "1234567890npduy2f"
  }
}

Technical or conformance issues with any properties of the Order, including in an orderedItem, MUST cause the Booking System to respond with only the appropriate OpenBookingError and associated status code. Following an UnableToProcessOrderItemError or OpportunityHasInsufficientCapacityError, the Broker is expected to retry the OrderQuote at C2 to get specific orderedItem level errors. Any validation errors raised at B regarding any property values MUST also be raised at C2 (and ideally also C1 if relevant), so it should be very unusual to receive an error at B.

HTTP/1.1 409 Conflict
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1.0

{
  "@context": "https://openactive.io/",
  "type": "UnableToProcessOrderItemError",
  "description": "An error occurred while processing the items within this booking."
}

For the Booking Flow with Approval specifically, the Broker decides to proceed from A to B by supplying a minimal Order to B that contains just the orderProposalVersion and any additional payment data if reauthorisation was required.

PUT /api/orders/e11429ea-467f-4270-ab62-e47368996fe8 HTTP/1.1
Host: example.com
Date: Mon, 8 Oct 2018 20:52:35 GMT
Accept: application/vnd.openactive.booking+json; version=1.0

{
  "@context": "https://openactive.io/",
  "type": "Order",
  "orderProposalVersion": "https://api.example.com/order-proposals/358105b4-e571-43fa-b737-906d319c6a32/version/8eb1a6ce-3f5b-40b0-87a7-bddb4c5518bd",
  "payment": {
    "type": "Payment",
    "name": "AcmeBroker Points",
    "identifier": "1234567890npduy2f"
  }
}

9.2.7 Order Deletion

Deleting an Order allows for the whole Booking Flow to be reversed for fatal error and testing scenarios.

When an Order is deleted the Booking System SHOULD hard delete it as though it had not been created in the first place, but MAY soft delete it providing all related personal data is purged. The audit for the deletion is guaranteed to be stored in the Broker in all cases.

The Broker MUST NOT use Order Deletion for cancellation, but instead only use it in the unusual case of a fatal error or testing. An appropriate approach for cancellation is defined below.

The corresponding Order MUST be marked as deleted in the Orders feed.

DELETE /api/orders/e11429ea-467f-4270-ab62-e47368996fe8 HTTP/1.1
Host: example.com
Date: Mon, 8 Oct 2018 20:52:35 GMT
Accept: application/vnd.openactive.booking+json; version=1.0

An Order Deletion request MUST simply return a 204 success status when an Order is successfully deleted.

HTTP/1.1 204 No Content
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1.0

An Order Deletion request MUST return a 404 status when the specified Order is not recognised, and SHOULD return a NotFoundError response.

HTTP/1.1 404 Not Found
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1.0

{
  "@context": "https://openactive.io/",
  "type": "NotFoundError",
  "description": "This Order does not exist."
}

9.2.8 Order Cancellation

Cancellation of an Order may be requested by the Customer. OrderItems omitted from the PATCH request MUST be ignored.

PATCH /api/orders/e11429ea-467f-4270-ab62-e47368996fe8 HTTP/1.1
Host: example.com
Date: Mon, 8 Oct 2018 20:52:35 GMT
Accept: application/vnd.openactive.booking+json; version=1.0

{
  "@context": "https://openactive.io/",
  "type": "Order",
  "orderedItem": [
    {
      "type": "OrderItem",
      "id": "https://example.com/api/orders/123e4567-e89b-12d3-a456-426655440000/order-items/1234",
      "orderItemStatus": "https://openactive.io/CustomerCancelled"
    }
  ]
}

The cancellation request succeeds and fails atomically.

HTTP/1.1 204 No Content
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1.0

HTTP/1.1 400 Bad Request
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1.0

{
  "@context": "https://openactive.io/",
  "type": "CancellationNotPermittedError",
  "description": "The horse has already been fed, and cannot be put back in the box."
}

A PATCH to update orderItemStatus MUST have the value https://openactive.io/CustomerCancelled, as that is the only permissible value based on the logic defined in this version of the specification. If another value for orderItemStatus is specified the endpoint MUST return an PatchNotAllowedOnProperty error with its status code.

HTTP/1.1 400 Bad Request
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1.0

{
  "@context": "https://openactive.io/",
  "type": "PatchNotAllowedOnProperty",
  "instance": "https://openactive.io/orderItemStatus",
  "description": "Only 'https://openactive.io/CustomerCancelled' is permitted for this property."
}

If the PATCH request includes any properties other than type, @context, id, orderedItem and orderItemStatus (excluding any properties with a custom namespace), the endpoint MUST return a PatchContainsExcessiveProperties error with its status code.

HTTP/1.1 400 Bad Request
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1.0

{
  "@context": "https://openactive.io/",
  "type": "PatchContainsExcessiveProperties",
  "description": "PATCH includes unexpected properties that are not permitted."
}

9.2.9 Orders RPDE feed

This feed is described at length in the Orders feed section.

An illustrative request and response is provided here.

GET /api/orders-rpde HTTP/1.1
Host: example.com
Date: Mon, 8 Oct 2018 20:52:35 GMT
Accept: application/vnd.openactive.booking+json; version=1.0

HTTP/1.1 200 OK
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1.0

{
  "next": "/api/orders-rpde?afterTimestamp=1521565719&afterId=e11429ea-467f-4270-ab62-e47368996fe8",
  "items": [
    {
      "state": "updated",
      "kind": "Order",
      "id": "e11429ea-467f-4270-ab62-e47368996fe8",
      "modified": 1521565719,
      "data": {
        "@context": "https://openactive.io/",
        "type": "Order",
        "id": "https://example.com/api/orders/e11429ea-467f-4270-ab62-e47368996fe8",
        "seller": {
          "type": "Organization",
          "identifier": "CRUOZWJ1",
          "name": "Better",
          "taxMode": "https://openactive/TaxGross",
          "legalName": "Greenwich Leisure Limited",
          "description": "A charitable social enterprise for all the community",
          "url": "https://www.better.org.uk",
          "logo": {
            "type": "ImageObject",
            "url": "http://data.better.org.uk/images/logo.png"
          },
          "telephone": "020 3457 8700",
          "email": "[email protected]",
          "vatID": "GB 789 1234 56",
          "address": {
            "type": "PostalAddress",
            "streetAddress": "Alan Peacock Way",
            "addressLocality": "Village East",
            "addressRegion": "Middlesbrough",
            "postalCode": "TS4 3AE",
            "addressCountry": "GB"
          },
          "termsOfService": [
            {
              "type": "Terms",
              "name": "Privacy Policy",
              "url": "https://example.com/privacy-policy"
            },
            {
              "type": "Terms",
              "name": "Terms and Conditions",
              "url": "https://example.com/terms-and-conditions"
            }
          ]
        },
        "orderedItem": [
          {
            "type": "OrderItem",
            "id": "https://example.com/api/orders/123e4567-e89b-12d3-a456-426655440000/order-items/1234",
            "orderItemStatus": "https://openactive.io/OrderConfirmed",
            "allowCustomerCancellationFullRefund": true,
            "unitTaxSpecification": [
              {
                "type": "TaxChargeSpecification",
                "name": "VAT at 0% for EU transactions",
                "price": 1,
                "priceCurrency": "GBP",
                "rate": 0.2
              }
            ],
            "acceptedOffer": {
              "type": "Offer",
              "id": "https://example.com/events/452#/offers/878",
              "description": "Winger space for Speedball.",
              "name": "Speedball winger position",
              "price": 10,
              "priceCurrency": "GBP",
              "validFromBeforeStartDate": "P6D",
              "latestCancellationBeforeStartDate": "P1D"
            },
            "orderedItem": {
              "type": "ScheduledSession",
              "id": "https://example.com/events/452/subEvents/132"
            }
          }
        ],
        "totalPaymentDue": {
          "type": "PriceSpecification",
          "price": 5,
          "priceCurrency": "GBP"
        },
        "totalTaxSpecification": [
          {
            "type": "TaxChargeSpecification",
            "name": "VAT at 20%",
            "price": 1,
            "priceCurrency": "GBP",
            "rate": 0.2
          }
        ]
      }
    }
  ]
}

9.2.10 Order Status

A Booking System SHOULD provide an endpoint to allow a Broker to retrieve complete Orders. In future versions of the specification, endpoints may be provided which permit a Broker to see all Orders created by a Customer. In this current implementation, the Broker MUST keep its own record of Orders as described elsewhere in this specification, and not rely on this RECOMMENDED Order Status endpoint.

GET /api/orders/e11429ea-467f-4270-ab62-e47368996fe8 HTTP/1.1
Host: example.com
Date: Mon, 8 Oct 2018 20:52:35 GMT
Accept: application/vnd.openactive.booking+json; version=1.0

HTTP/1.1 200 OK
Date: Mon, 8 Oct 2018 20:52:36 GMT
Content-Type: application/vnd.openactive.booking+json; version=1.0
Location: /api/orders/e11429ea-467f-4270-ab62-e47368996fe8

{
  "@context": "https://openactive.io/",
  "type": "Order",
  "id": "https://example.com/api/orders/e11429ea-467f-4270-ab62-e47368996fe8",
  "brokerRole": "https://openactive.io/BrokerAgent",
  "broker": {
    "type": "Organization",
    "name": "MyFitnessApp",
    "url": "https://myfitnessapp.example.com",
    "description": "A fitness app for all the community",
    "logo": {
      "type": "ImageObject",
      "url": "http://data.myfitnessapp.org.uk/images/logo.png"
    },
    "address": {
      "type": "PostalAddress",
      "streetAddress": "Alan Peacock Way",
      "addressLocality": "Village East",
      "addressRegion": "Middlesbrough",
      "postalCode": "TS4 3AE",
      "addressCountry": "GB"
    }
  },
  "customer": {
    "type": "Person",
    "email": "[email protected]",
    "telephone": "020 811 8055",
    "givenName": "Geoff",
    "familyName": "Capes"
  },
  "seller": {
    "type": "Organization",
    "identifier": "CRUOZWJ1",
    "name": "Better",
    "taxMode": "https://openactive/TaxGross",
    "legalName": "Greenwich Leisure Limited",
    "description": "A charitable social enterprise for all the community",
    "url": "https://www.better.org.uk",
    "logo": {
      "type": "ImageObject",
      "url": "http://data.better.org.uk/images/logo.png"
    },
    "telephone": "020 3457 8700",
    "email": "[email protected]",
    "vatID": "GB 789 1234 56",
    "address": {
      "type": "PostalAddress",
      "streetAddress": "Alan Peacock Way",
      "addressLocality": "Village East",
      "addressRegion": "Middlesbrough",
      "postalCode": "TS4 3AE",
      "addressCountry": "GB"
    },
    "termsOfService": [
      {
        "type": "Terms",
        "name": "Privacy Policy",
        "url": "https://example.com/privacy-policy"
      },
      {
        "type": "Terms",
        "name": "Terms and Conditions",
        "url": "https://example.com/terms-and-conditions"
      }
    ]
  },
  "bookingService": {
    "type": "BookingService",
    "name": "Playwaze",
    "url": "http://www.playwaze.com",
    "termsOfService": [
      {
        "type": "Terms",
        "url": "https://brokerexample.com/terms.html"
      }
    ]
  },
  "orderedItem": [
    {
      "type": "OrderItem",
      "id": "https://example.com/api/orders/123e4567-e89b-12d3-a456-426655440000/order-items/1234",
      "orderItemStatus": "https://openactive.io/OrderConfirmed",
      "allowCustomerCancellationFullRefund": true,
      "unitTaxSpecification": [
        {
          "type": "TaxChargeSpecification",
          "name": "VAT at 0% for EU transactions",
          "price": 1,
          "priceCurrency": "GBP",
          "rate": 0.2
        }
      ],
      "acceptedOffer": {
        "type": "Offer",
        "id": "https://example.com/events/452#/offers/878",
        "description": "Winger space for Speedball.",
        "name": "Speedball winger position",
        "price": 10,
        "priceCurrency": "GBP",
        "validFromBeforeStartDate": "P6D",
        "latestCancellationBeforeStartDate": "P1D"
      },
      "orderedItem": {
        "type": "ScheduledSession",
        "identifier": 123,
        "id": "https://example.com/events/452/subEvents/132",
        "eventStatus": "https://schema.org/EventScheduled",
        "startDate": "2018-10-30T11:00:00Z",
        "endDate": "2018-10-30T12:00:00Z",
        "duration": "PT1H",
        "superEvent": {
          "type": "SessionSeries",
          "id": "https://example.com/events/452",
          "name": "Speedball",
          "organizer": {
            "type": "Organization",
            "name": "Central Speedball Association",
            "url": "http://www.speedball-world.com"
          },
          "location": {
            "type": "Place",
            "url": "https://www.everyoneactive.com/centres/Middlesbrough-Sports-Village",
            "name": "Middlesbrough Sports Village",
            "identifier": "0140",
            "address": {
              "type": "PostalAddress",
              "streetAddress": "Alan Peacock Way",
              "addressLocality": "Village East",
              "addressRegion": "Middlesbrough",
              "postalCode": "TS4 3AE",
              "addressCountry": "GB"
            },
            "geo": {
              "type": "GeoCoordinates",
              "latitude": 54.543964,
              "longitude": -1.20978500000001
            }
          }
        }
      },
      "accessToken": [
        {
          "type": "Barcode",
          "text": "0123456789"
        }
      ]
    }
  ],
  "totalPaymentDue": {
    "type": "PriceSpecification",
    "price": 5,
    "priceCurrency": "GBP"
  },
  "totalTaxSpecification": [
    {
      "type": "TaxChargeSpecification",
      "name": "VAT at 20%",
      "price": 1,
      "priceCurrency": "GBP",
      "rate": 0.2
    }
  ],
  "payment": {
    "type": "Payment",
    "name": "AcmeBroker Points",
    "identifier": "1234567890npduy2f"
  }
}

9.2.11 URL discovery

Discovery of URLs is an implicit part of the design of this specification, and Brokers SHOULD avoid hard-coding URLs for specific actions into their applications and client libraries. Brokers SHOULD use most applicable URL discovered at the point in the workflow they are currently in - e.g. not use a cached URL that has been previously successfully used. They should also not attempt to create URLs for a specific action based on patterns within previously used URLs.

It is the responsibility of Booking Systems to advertise the URL for further activity in the booking workflow at the point of need or via the [Dataset-API-Discovery] specification. For example they MUST advertise the URL for the Order resource in the Orders Orders feed by including the id property within the Order.

10.1.1 schema:Order

10.1.2 oa:OrderQuote

OrderQuote subclasses Order, and includes all of the above properties as specified for Order with the addition of oa:lease, oa:orderRequiresApproval, and with totalPaymentDue only required in the response.

10.1.3 oa:OrderProposal

OrderProposal subclasses OrderQuote, and includes all of the above properties as specified for OrderQuote, with the further addition of oa:orderProposalStatus, oa:orderSellerNote, oa:orderCustomerNote, and with totalPaymentDue required in the request and response, and Orders feed.

10.1.4 schema:Organization for seller

The seller MUST be a schema:Organization with the following properties, in order for tax receipts to be successfully generated.

The seller is specified with each Order to account for scenarios where multiple Seller brands are in use.