Open Booking API 1.0 CR2

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 an Order UUID, which is used to uniquely identify the OrderQuote / 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 capability 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 an Order UUID.
• 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 Order UUID MUST be regenerated to allow for a clean retry of the booking. The Order UUID MUST NOT be regenerated for expected errors (status code 4xx).

ii) C1 - Broker call with OrderQuote including the Order 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 Order UUID if it is supported, otherwise it provides a simple availability and totalPaymentDue confirmation. An OrderQuote response with HTTP Status 200 MUST 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.
• The OrderQuote response MUST include totalPaymentDue, which allows the Broker to update any UI with the total.
• The OrderQuote response 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, but excluding those places already reserved for this Order UUID by previous calls to C1 and C2.
• The OrderQuote response 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.
• If a viable payment reconciliation route is available between the Broker and the Seller that requires more than just the identifier property of the Payment to be included in B, the payment property MUST be included at C1, as per Payment reconciliation detail validation. This ensures that a viable payment reconciliation route is available before the Customer starts to enter their data.
• 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 consent to the most recently modified version of such terms. The Broker MAY remember the consent previously given by the Customer based on the url and dateModified of the Terms, only if dateModified is provided, and if consent for storing such preferences is given by the Customer.
• attendee and orderItemIntakeFormResponse data is be captured at this stage if specified via attendeeDetailsRequired and orderItemIntakeForm in the C1 response, respectively.
• If payment initiation is optional, 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 the Order 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 Order 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.
• If a viable payment reconciliation route is available between the Broker and the Seller that requires more than just the identifier property of the Payment to be included in B, the payment property MUST be included at C2, as per Payment reconciliation detail validation.
• 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 payment is not to be initiated or totalPaymentDue is 0, payment details MUST NOT be captured.

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

• The Order @id, which includes the Order 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 was not initiated or totalPaymentDue is 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 Order 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 the Order 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 was not initiated or totalPaymentDue is 0, the payment property MUST NOT be included in the Order request or response, and the Booking System MUST proceed to create a payment-free Order.

• Error responses MUST be returned for any Payment Error Conditions.

• 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 Order UUID. As the call is idempotent, the Booking System will need to track the Order 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 Order 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, an Order UUID clash is assumed, a 500 response of with OrderAlreadyExistsError is returned by the Booking System, and a new Order 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 Order UUID MUST be regenerated to allow for a clean retry of the booking. The Order UUID MUST NOT be regenerated for expected errors (status code 4xx).

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

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 was not initiated or totalPaymentDue is 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

1. Propose: Customer submits payment details, and submits a proposed booking

2. Approve: Seller approves the booking, after a period of time

3. 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 an Order UUID, which is used to uniquely identify the OrderQuote / OrderProposal / 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 the openBookingFlowRequirement of any Offer referenced in the OrderProposal request includes https://openactive.io/OpenBookingNegotiation within the open data, 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.

  The Booking System MUST generate a new OrderProposal Version UUID, which is a unique UUID string representation strictly as defined in [RFC4122], separate to the Order UUID, for the initial OrderProposal, and subsequently for each amendment made (if Proposal Amendment is supported).

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 within its open data 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 payment is not to be initiated or totalPaymentDue is 0, 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 Order 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 Order 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 MUST be atomic.

• The returned OrderProposal also MUST contain an orderProposalVersion, which is constructed from the @id of the OrderProposal, combined with an additional OrderProposal Version UUID.

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

• 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 request MAY include an orderCustomerNote in order to allow the Customer to ask a question about this Opportunity, as the beginning of a Message Exchange. This is only permissible if the any Offer referenced in the OrderProposal includes an openBookingFlowRequirement property within the open data that contains 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 MUST 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 was not initiated or totalPaymentDue is 0, the payment property MUST NOT be included in the OrderProposal request or response.

• Error responses MUST be returned for any Payment Error Conditions.

• 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 Order UUID. As the call is idempotent, the Booking System will need to track the Order 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 Order 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 Order UUID clash is assumed, a 500 response of with OrderAlreadyExistsError is returned by the Booking System, and a new Order 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 Order UUID MUST be regenerated to allow for a clean retry of the booking. The Order 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 in the revised OrderProposal, payment initiation is now optional, 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.

• If payment details were not previously captured and payment is now to be initiated, due to the revised OrderProposal, they MUST be captured. If totalPaymentDue is 0, payment details MUST NOT be captured.

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

• If payment is still appropriate given the latest orderProposalVersion that the Customer has agreed to (see Proposal Amendment), and if totalPaymentDue has increased or if the previous Payment Authorisation has expired, the Broker MUST re-authorise the total amount with the Payment Provider.

• 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 Order 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 then 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.

• If a newer version of the OrderProposal is available compared with the orderProposalVersion provided by the Broker, then B MUST return an OrderProposalVersionOutdatedError with associated status code.

• 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. The Booking System MUST NOT reflect back the orderProposalVersion in its response to B.

• All other behaviour is identical to the Simple Booking Flow step vii. The Broker stores the response to B to completely replace their previously stored OrderProposal, and the previous OrderProposal is set to "state": "deleted" in the Orders feed. The orderProposalVersion MUST NOT be included in the new Order.

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.

If the same attendee is used across multiple OrderItems, a duplicate Person MUST be provided for each of these OrderItems. The Broker may choose to design their user interface to minimise repeat data entry (e.g. by allowing the Customer to enter attendee details first, then later assigning them to OrderItems), however this is outside the scope of the specification.

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 Offer 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 Offer 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 totalPaymentTax, 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 either 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 identifiers

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 totalPaymentTax 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.io/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.

7.6.1 Free opportunities

Free Opportunities, defined as those with at least one applicable Offer with a price of 0, MUST follow the same workflow as paid Opportunities.

For Offers with a price of 0:

• The prepayment property of the Offer MUST be either https://openactive.io/Unavailable or unspecified.
• The Offer MAY not include priceCurrency.
• If a priceCurrency is not available then Brokers SHOULD communicate "Free" or equivalent when referencing a zero price.

When an Order or OrderProposal involves exclusively Free Opportunities the totalPaymentDue will be 0 regardless of the prepayment property values. In this case, no interaction with a Payment Provider is required, the payment property MAY be omitted at C1 and C2 (depending on Payment Reconciliation Detail Validation), and MUST be omitted at B or P.

7.6.2 Payment error conditions

At B or P the Booking System MUST produce an error response in the following cases:

• If the payment property is expected in the request (as within totalPaymentDue: prepayment is https://openactive.io/Required, or if prepayment not supported, price is not 0) but not provided, then a MissingPaymentDetailsError MUST be returned .
• If the payment property is provided but not expected in the request (as within totalPaymentDue: prepayment is https://openactive.io/Unavailable or price is 0), then an UnnecessaryPaymentDetailsError MUST be returned.
• If the payment property does not include identifier, 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.

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 ageRestriction 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 an array of oa:additionalAdmissionRestriction on the SessionSeries, FacilityUse, Event, HeadlineEvent or CourseInstance, and the Broker MUST communicate these restrictions clearly during the booking process.

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

8.1.2 Opportunity data properties

For requests to C1, C2, P, and B, and for items in the Orders feed, the Opportunity Data within the orderedItem property of an OrderItem MUST only include the properties @type and @id. The orderedItem property of all OrderItems MAY be excluded from the Orders feed if the Booking System does not support Replacement.

For responses from C1, C2, P, and B, and from the Order Status endpoint, the Opportunity Data within the orderedItem property of an OrderItem MUST correspond exactly with the model used within the Opportunity Data [RPDE] open feeds. For example if properties within a SessionSeries and ScheduledSession are used in the open feeds, corresponding properties must be used within objects of the same types within the orderedItem.

See the [Modelling-Opportunity-Data] specification for more information on these types.

For such responses, the Opportunity Data MUST include the following properties:

• @type
• @id and name of the bookable Opportunity
• url
• location (including name, and either or ideally both of address or geo)
• activity
• startDate

For such responses, the following properties are RECOMMENDED:

• endDate
• duration
• ageRange
• genderRestriction
• eventStatus
• maximumAttendeeCapacity or maximumUses
• remainingAttendeeCapacity or remainingUses

For such responses, the Opportunity Data MUST NOT include the following properties:

• offers (as the relevant Offer will be returned in acceptedOffer)
• subEvent or event (as the opportunity should be bookable, and therefore of sufficient granularity)
• organizer or provider (as this is provided by the seller property of the Order)

Where relevant it is expected that the Opportunity Data for such responses includes superEvent or facilityUse to allow for a SessionSeries or FacilityUse to be referenced from a SessionSeries or Slot, for example.

8.1.3 acceptedOffer properties

The Booking System MUST include all applicable properties within the acceptedOffer consistently in responses to C1, C2, P, and B. acceptedOffer MUST also include the same properties in the Orders feed, unless the Booking System does not support Replacement.

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 (e.g. when an attendee arrives early), is currently outside the scope of this specification.

Hence within this version of the specification any OrderItem @id submitted to the Order Cancellation endpoint MUST reference an Opportunity with a startDate in the future.

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 orderItemStatus is not yet set to https://openactive.io/CustomerAttended, and allowCustomerCancellationFullRefund is true, and either latestCancellationBeforeStartDate is unspecified and startDate is in the future, or 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 to the Order Cancellation endpoint 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 Customer, 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 or OrderProposal item is found by the Broker on the feed. Due to the Order or OrderProposal being stored during the Payment Authorisation stage, the Broker should always have a matching Order or OrderProposal for any Order UUID on the Orders feed even if it has been soft-deleted. This would make an unrecognised Order or OrderProposal an impossible scenario, and hence an unrecognised Order or OrderProposal should be logged as a serious error within the Broker and promptly investigated.

The RPDE id of an OrderProposal MUST differ from the RPDE id of its related Order. The OrderProposal is marked as deleted at B, and the related Order will not appear in the Orders feed until it is next updated.

An Order MUST NOT be set to "state": "deleted" in the Orders feed by the Booking System, except as a result of Order Deletion, or when authorisation to access a particular Seller has been revoked. An Order in the Orders feed marked as deleted outside of Order Deletion should be logged as a serious error within the Broker and promptly investigated, and SHOULD NOT trigger an immediate deletion of the Order by the Broker, to allow for the issue to be resolved.

8.4.2 Order stores with eventual consistency

It is important that the storage used by the Broker for Orders provides a linearisability 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 and OrderProposals 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 or OrderProposal in the feed MUST result in a change to the RPDE modified property associated with it.

8.4.4 Broker: Processing the Orders feed

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

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

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

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

• totalPaymentTax (if taxCalculationExcluded is not true)
• totalPaymentDue
• orderProposalStatus (OrderProposal only)
• orderProposalVersion (OrderProposal only)

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

For OrderItem in both Order and OrderProposal:

• orderItemStatus
• allowCustomerCancellationFullRefund
• accessPass
• accessCode
• additionalProperty
• cancellationMessage
• customerNotice
• acceptedOffer
• unitTaxSpecification
• orderedItem (including only @type and @id properties)

And for OrderItem in OrderProposal it additionally includes:

• attendeeDetailsRequired
• attendee
• orderItemIntakeForm
• orderItemIntakeFormResponse

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

• acceptedOffer
• unitTaxSpecification
• orderedItem

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

• @type, @id and identifier (the Order UUID) of the Order or OrderProposal
• @type and @id of the OrderItem
• taxCalculationExcluded (only included if its value is true)

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

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

Properties in Order and OrderProposal:

• bookingService
• broker
• brokerRole
• seller
• customer
• orderNumber
• payment

Properties in OrderItem within Order only:

• attendeeDetailsRequired
• attendee
• orderItemIntakeForm
• orderItemIntakeFormResponse

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

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

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

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

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

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

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.

OrderProposals MUST be stored by the Broker based on a successful response to P, and Orders MUST be stored by the Broker based on a successful response to B.

New Orders and OrderProposals MUST NOT be included in the feed until they have been updated at least once. This minimises the volume of updates 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, replacement, refund calculation and notification

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

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

• Cancellation: Updated https://openactive.io/CustomerCancelled or https://openactive.io/SellerCancelled values for orderItemStatus, indicating the item is cancelled and a refund due if necessary.
• Replacement: Updated @type and @id within the orderedItem, and associated updates to acceptedOffer and unitTaxSpecification, indicating the item has been replaced by the Seller with an equivalent item of the same or lower price.

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

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

For a Replacement, an updated acceptedOffer (and unitTaxSpecification, if relevant) MAY be included in the OrderItem, and MUST then constitute a snapshot and MUST remain unchanged by the Booking System except for in the case of a further Replacement. The value of prepayment within the acceptedOffer MUST NOT be change through Replacement.

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

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

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

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

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

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

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 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 requires the Orders feed to not include the full contents of the Opportunities within the orderedItem, and instead only includes the Opportunity properties @type and @id. Additionally the orderedItem property of the OrderItem is only required within the Orders feed if Replacement is supported.

Hence the Broker MUST store the Opportunity references @type and @id at B, MUST monitor the Opportunity Data open feeds for updates to the referenced information, and MUST provide a notification to the Customer for substantive changes to the same Opportunity; specifically: any changes to the Opportunity name, startDate, endDate, duration or meetingPoint properties, and any changes to the name, address or geo properties within location.

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.4.11 Other notifications

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

• accessCode and/or accessPass - A notification that the access details for the Opportunity have changed

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

• allowCustomerCancellationFullRefund - Automated cancellation with a full refund is no longer possible via the Broker.

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

• additionalProperty - The details to use for payment reconciliation have changed

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 accessPass array.

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

"accessPass": [
  {
    "@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 accessPass 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.

Additionally where use of an existing barcode is desirable (for example, the barcode on a Broker's own membership card) the Broker MAY include a Barcode in the accessPass property against individual OrderItems in the request to B. If the Booking System is able to accept such existing barcodes, it SHOULD reflect back the specified Barcode in the accessPass array in the response along with any other valid access control options.

"accessPass": [
  {
    "@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 Order 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 Order 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 Order 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. If persisted, /order-quote-templates appear immediately in /order-quotes, in order that they can be deleted via OrderQuote Deletion.
• /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 can be handled by the same underlying code 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, much of the business logic can be shared between 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

{
  "@context": "https://openactive.io/",
  "@type": "OrderQuote",
  "brokerRole": "https://openactive.io/AgentBroker",
  "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"
    }
  },
  "seller": {
    "@type": "Organization",
    "@id": "https://example.com/api/organisations/123"
  },
  "orderedItem": [
    {
      "@type": "OrderItem",
      "position": 0,
      "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

{
  "@context": "https://openactive.io/",
  "@type": "OrderQuote",
  "@id": "https://example.com/api/order-quotes/e11429ea-467f-4270-ab62-e47368996fe8",
  "orderRequiresApproval": false,
  "brokerRole": "https://openactive.io/AgentBroker",
  "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"
    }
  },
  "seller": {
    "@type": "Organization",
    "@id": "https://example.com/api/organisations/123",
    "identifier": "CRUOZWJ1",
    "name": "Better",
    "taxMode": "https://openactive.io/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": "PrivacyPolicy",
        "name": "Privacy Policy",
        "url": "https://example.com/privacy-policy",
        "requiresExplicitConsent": false
      },
      {
        "@type": "TermsOfUse",
        "name": "Terms and Conditions",
        "url": "https://example.com/terms-and-conditions",
        "dateModified": "2019-04-16T20:31:13Z",
        "requiresExplicitConsent": true
      }
    ]
  },
  "bookingService": {
    "@type": "BookingService",
    "name": "Playwaze",
    "url": "http://www.playwaze.com",
    "termsOfService": [
      {
        "@type": "Terms",
        "name": "Terms of Service",
        "url": "https://brokerexample.com/terms.html",
        "requiresExplicitConsent": false
      }
    ]
  },
  "lease": {
    "@type": "Lease",
    "leaseExpires": "2018-10-01T11:00:00Z"
  },
  "orderedItem": [
    {
      "@type": "OrderItem",
      "position": 0,
      "allowCustomerCancellationFullRefund": true,
      "unitTaxSpecification": [
        {
          "@type": "TaxChargeSpecification",
          "name": "VAT at 20%",
          "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",
        "identifier": 123,
        "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://api.example.com/events/452",
          "name": "Bodypump",
          "activity": [
            {
              "type": "Concept",
              "id": "https://openactive.io/activity-list#5e78bcbe-36db-425a-9064-bf96d09cc351",
              "prefLabel": "Bodypump™",
              "inScheme": "https://openactive.io/activity-list"
            }
          ],
          "duration": "PT1H",
          "url": "https://example.com/events/452",
          "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"
  },
  "totalPaymentTax": [
    {
      "@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 totalPaymentTax MUST be calculated including any OrderItems that exclusively contain IncompleteAttendeeDetailsError or IncompleteIntakeFormError errors, and excluding any OrderItems that include any other errors.

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

{
  "@context": "https://openactive.io/",
  "@type": "OrderQuote",
  "@id": "https://example.com/api/order-quotes/e11429ea-467f-4270-ab62-e47368996fe8",
  "orderRequiresApproval": false,
  "brokerRole": "https://openactive.io/AgentBroker",
  "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"
    }
  },
  "seller": {
    "@type": "Organization",
    "@id": "https://example.com/api/organisations/123",
    "identifier": "CRUOZWJ1",
    "name": "Better",
    "taxMode": "https://openactive.io/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": "PrivacyPolicy",
        "name": "Privacy Policy",
        "url": "https://example.com/privacy-policy",
        "requiresExplicitConsent": false
      },
      {
        "@type": "TermsOfUse",
        "name": "Terms and Conditions",
        "url": "https://example.com/terms-and-conditions",
        "dateModified": "2019-04-16T20:31:13Z",
        "requiresExplicitConsent": true
      }
    ]
  },
  "bookingService": {
    "@type": "BookingService",
    "name": "Playwaze",
    "url": "http://www.playwaze.com",
    "termsOfService": [
      {
        "@type": "Terms",
        "name": "Terms of Service",
        "url": "https://brokerexample.com/terms.html",
        "requiresExplicitConsent": false
      }
    ]
  },
  "lease": {
    "@type": "Lease",
    "leaseExpires": "2018-10-01T11:00:00Z"
  },
  "orderedItem": [
    {
      "@type": "OrderItem",
      "position": 0,
      "orderItemStatus": "https://openactive.io/OrderItemConfirmed",
      "allowCustomerCancellationFullRefund": true,
      "unitTaxSpecification": [
        {
          "@type": "TaxChargeSpecification",
          "name": "VAT at 20%",
          "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",
        "identifier": 123,
        "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://api.example.com/events/452",
          "name": "Bodypump",
          "activity": [
            {
              "type": "Concept",
              "id": "https://openactive.io/activity-list#5e78bcbe-36db-425a-9064-bf96d09cc351",
              "prefLabel": "Bodypump™",
              "inScheme": "https://openactive.io/activity-list"
            }
          ],
          "duration": "PT1H",
          "url": "https://example.com/events/452",
          "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"
  },
  "totalPaymentTax": [
    {
      "@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

{
  "@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

{
  "@context": "https://openactive.io/",
  "@type": "OrderQuote",
  "brokerRole": "https://openactive.io/AgentBroker",
  "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"
    }
  },
  "seller": {
    "@type": "Organization",
    "@id": "https://example.com/api/organisations/123"
  },
  "customer": {
    "@type": "Person",
    "email": "[email protected]",
    "telephone": "020 811 8055",
    "givenName": "Geoff",
    "familyName": "Capes"
  },
  "orderedItem": [
    {
      "@type": "OrderItem",
      "position": 0,
      "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

{
  "@context": "https://openactive.io/",
  "@type": "OrderQuote",
  "@id": "https://example.com/api/order-quotes/e11429ea-467f-4270-ab62-e47368996fe8",
  "orderRequiresApproval": false,
  "brokerRole": "https://openactive.io/AgentBroker",
  "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"
    }
  },
  "seller": {
    "@type": "Organization",
    "@id": "https://example.com/api/organisations/123",
    "identifier": "CRUOZWJ1",
    "name": "Better",
    "taxMode": "https://openactive.io/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": "PrivacyPolicy",
        "name": "Privacy Policy",
        "url": "https://example.com/privacy-policy",
        "requiresExplicitConsent": false
      },
      {
        "@type": "TermsOfUse",
        "name": "Terms and Conditions",
        "url": "https://example.com/terms-and-conditions",
        "dateModified": "2019-04-16T20:31:13Z",
        "requiresExplicitConsent": true
      }
    ]
  },
  "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",
        "name": "Terms of Service",
        "url": "https://brokerexample.com/terms.html",
        "requiresExplicitConsent": false
      }
    ]
  },
  "lease": {
    "@type": "Lease",
    "leaseExpires": "2018-10-01T11:00:00Z"
  },
  "orderedItem": [
    {
      "@type": "OrderItem",
      "position": 0,
      "allowCustomerCancellationFullRefund": true,
      "unitTaxSpecification": [
        {
          "@type": "TaxChargeSpecification",
          "name": "VAT at 20%",
          "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",
        "identifier": 123,
        "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://api.example.com/events/452",
          "name": "Bodypump",
          "activity": [
            {
              "type": "Concept",
              "id": "https://openactive.io/activity-list#5e78bcbe-36db-425a-9064-bf96d09cc351",
              "prefLabel": "Bodypump™",
              "inScheme": "https://openactive.io/activity-list"
            }
          ],
          "duration": "PT1H",
          "url": "https://example.com/events/452",
          "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"
  },
  "totalPaymentTax": [
    {
      "@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 totalPaymentTax MUST be calculated including any OrderItems that exclusively contain IncompleteAttendeeDetailsError or IncompleteIntakeFormError errors, and excluding any OrderItems that include any other errors.

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

{
  "@context": "https://openactive.io/",
  "@type": "OrderQuote",
  "@id": "https://example.com/api/order-quotes/e11429ea-467f-4270-ab62-e47368996fe8",
  "orderRequiresApproval": false,
  "brokerRole": "https://openactive.io/AgentBroker",
  "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"
    }
  },
  "seller": {
    "@type": "Organization",
    "@id": "https://example.com/api/organisations/123",
    "identifier": "CRUOZWJ1",
    "name": "Better",
    "taxMode": "https://openactive.io/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": "PrivacyPolicy",
        "name": "Privacy Policy",
        "url": "https://example.com/privacy-policy",
        "requiresExplicitConsent": false
      },
      {
        "@type": "TermsOfUse",
        "name": "Terms and Conditions",
        "url": "https://example.com/terms-and-conditions",
        "dateModified": "2019-04-16T20:31:13Z",
        "requiresExplicitConsent": true
      }
    ]
  },
  "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",
        "name": "Terms of Service",
        "url": "https://brokerexample.com/terms.html",
        "requiresExplicitConsent": false
      }
    ]
  },
  "lease": {
    "@type": "Lease",
    "leaseExpires": "2018-10-01T11:00:00Z"
  },
  "orderedItem": [
    {
      "@type": "OrderItem",
      "position": 0,
      "orderItemStatus": "https://openactive.io/OrderItemConfirmed",
      "allowCustomerCancellationFullRefund": true,
      "unitTaxSpecification": [
        {
          "@type": "TaxChargeSpecification",
          "name": "VAT at 20%",
          "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",
        "identifier": 123,
        "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://api.example.com/events/452",
          "name": "Bodypump",
          "activity": [
            {
              "type": "Concept",
              "id": "https://openactive.io/activity-list#5e78bcbe-36db-425a-9064-bf96d09cc351",
              "prefLabel": "Bodypump™",
              "inScheme": "https://openactive.io/activity-list"
            }
          ],
          "duration": "PT1H",
          "url": "https://example.com/events/452",
          "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"
  },
  "totalPaymentTax": [
    {
      "@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

{
  "@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/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

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

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

{
  "@context": "https://openactive.io/",
  "@type": "OrderProposal",
  "brokerRole": "https://openactive.io/AgentBroker",
  "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"
    }
  },
  "seller": {
    "@type": "Organization",
    "@id": "https://example.com/api/organisations/123"
  },
  "customer": {
    "@type": "Person",
    "email": "[email protected]",
    "telephone": "020 811 8055",
    "givenName": "Geoff",
    "familyName": "Capes"
  },
  "orderedItem": [
    {
      "@type": "OrderItem",
      "position": 0,
      "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
Location: /api/order-proposals/e11429ea-467f-4270-ab62-e47368996fe8

{
  "@context": "https://openactive.io/",
  "@type": "OrderProposal",
  "@id": "https://example.com/api/order-proposals/e11429ea-467f-4270-ab62-e47368996fe8",
  "orderNumber": "AB000001",
  "orderProposalVersion": "https://example.com/api/order-proposals/e11429ea-467f-4270-ab62-e47368996fe8/versions/8eb1a6ce-3f5b-40b0-87a7-bddb4c5518bd",
  "orderProposalStatus": "https://openactive.io/AwaitingSellerConfirmation",
  "brokerRole": "https://openactive.io/AgentBroker",
  "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"
    }
  },
  "seller": {
    "@type": "Organization",
    "@id": "https://example.com/api/organisations/123",
    "identifier": "CRUOZWJ1",
    "name": "Better",
    "taxMode": "https://openactive.io/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": "PrivacyPolicy",
        "name": "Privacy Policy",
        "url": "https://example.com/privacy-policy",
        "requiresExplicitConsent": false
      },
      {
        "@type": "TermsOfUse",
        "name": "Terms and Conditions",
        "url": "https://example.com/terms-and-conditions",
        "dateModified": "2019-04-16T20:31:13Z",
        "requiresExplicitConsent": true
      }
    ]
  },
  "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",
        "name": "Terms of Service",
        "url": "https://brokerexample.com/terms.html",
        "requiresExplicitConsent": false
      }
    ]
  },
  "orderedItem": [
    {
      "@type": "OrderItem",
      "position": 0,
      "orderItemStatus": "https://openactive.io/OrderItemProposed",
      "unitTaxSpecification": [
        {
          "@type": "TaxChargeSpecification",
          "name": "VAT at 20%",
          "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",
        "identifier": 123,
        "eventStatus": "https://schema.org/EventScheduled",
        "startDate": "2018-10-30T11:00:00Z",
        "endDate": "2018-10-30T12:00:00Z",
        "duration": "PT1H",
        "superEvent": {
          "@type": "SessionSeries",
          "@id": "https://api.example.com/events/452",
          "name": "Bodypump",
          "activity": [
            {
              "type": "Concept",
              "id": "https://openactive.io/activity-list#5e78bcbe-36db-425a-9064-bf96d09cc351",
              "prefLabel": "Bodypump™",
              "inScheme": "https://openactive.io/activity-list"
            }
          ],
          "url": "https://example.com/events/452",
          "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"
  },
  "totalPaymentTax": [
    {
      "@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

{
  "@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

{
  "@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

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

{
  "@context": "https://openactive.io/",
  "@type": "PatchNotAllowedOnProperty",
  "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

{
  "@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

{
  "@context": "https://openactive.io/",
  "@type": "Order",
  "brokerRole": "https://openactive.io/AgentBroker",
  "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"
    }
  },
  "seller": {
    "@type": "Organization",
    "@id": "https://example.com/api/organisations/123"
  },
  "customer": {
    "@type": "Person",
    "email": "[email protected]",
    "telephone": "020 811 8055",
    "givenName": "Geoff",
    "familyName": "Capes"
  },
  "orderedItem": [
    {
      "@type": "OrderItem",
      "position": 0,
      "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
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/AgentBroker",
  "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",
    "@id": "https://example.com/api/organisations/123",
    "identifier": "CRUOZWJ1",
    "name": "Better",
    "taxMode": "https://openactive.io/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": "PrivacyPolicy",
        "name": "Privacy Policy",
        "url": "https://example.com/privacy-policy",
        "requiresExplicitConsent": false
      },
      {
        "@type": "TermsOfUse",
        "name": "Terms and Conditions",
        "url": "https://example.com/terms-and-conditions",
        "dateModified": "2019-04-16T20:31:13Z",
        "requiresExplicitConsent": true
      }
    ]
  },
  "bookingService": {
    "@type": "BookingService",
    "name": "Playwaze",
    "url": "http://www.playwaze.com",
    "termsOfService": [
      {
        "@type": "Terms",
        "name": "Terms of Service",
        "url": "https://brokerexample.com/terms.html",
        "requiresExplicitConsent": false
      }
    ]
  },
  "orderedItem": [
    {
      "@type": "OrderItem",
      "@id": "https://example.com/api/orders/e11429ea-467f-4270-ab62-e47368996fe8#/orderedItem/1234",
      "position": 0,
      "orderItemStatus": "https://openactive.io/OrderItemConfirmed",
      "allowCustomerCancellationFullRefund": true,
      "unitTaxSpecification": [
        {
          "@type": "TaxChargeSpecification",
          "name": "VAT at 20%",
          "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",
        "identifier": 123,
        "eventStatus": "https://schema.org/EventScheduled",
        "startDate": "2018-10-30T11:00:00Z",
        "endDate": "2018-10-30T12:00:00Z",
        "duration": "PT1H",
        "superEvent": {
          "@type": "SessionSeries",
          "@id": "https://api.example.com/events/452",
          "name": "Bodypump",
          "activity": [
            {
              "type": "Concept",
              "id": "https://openactive.io/activity-list#5e78bcbe-36db-425a-9064-bf96d09cc351",
              "prefLabel": "Bodypump™",
              "inScheme": "https://openactive.io/activity-list"
            }
          ],
          "url": "https://example.com/events/452",
          "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
            }
          }
        }
      },
      "accessPass": [
        {
          "@type": "Barcode",
          "text": "0123456789"
        }
      ]
    }
  ],
  "totalPaymentDue": {
    "@type": "PriceSpecification",
    "price": 5,
    "priceCurrency": "GBP"
  },
  "totalPaymentTax": [
    {
      "@type": "TaxChargeSpecification",
      "name": "VAT at 20%",
      "price": 1,
      "priceCurrency": "GBP",
      "rate": 0.2
    }
  ],
  "payment": {
    "@type": "Payment",
    "name": "AcmeBroker Points",
    "identifier": "1234567890npduy2f"
  }
}