Skip to content

Commit d8b2505

Browse files
nickevansuknickevansuk
committed
Overrides and Indicative offers
1 parent 3bde3cc commit d8b2505

File tree

2 files changed

+342
-94
lines changed

2 files changed

+342
-94
lines changed

‎EditorsDraft/edit.html

+86-11
Original file line numberDiff line numberDiff line change
@@ -645,11 +645,11 @@
645645
The `ResellerBroker`'s purchase from the <a>Seller</a> is business-to-business, which is subject to the appropriate taxation based on the `ResellerBroker` as the <a>Customer</a>.
646646
The <a>Customer</a>'s purchase from the `ResellerBroker` is business-to-consumer, which is subject to the appropriate taxation based on the `ResellerBroker` as the <a>Seller</a>.
647647

648-
Hence any tax exception that the <a>Customer</a> may enjoy when purchasing directly from the <a>Seller</a> (e.g. if the <a>Seller</a> is an [VAT exempt eligible body](https://www.gov.uk/guidance/sport-supplies-that-are-vat-exempt-notice-70145)) is not relevant here, as no direct contractual relationship is formed between <a>Seller</a> and <a>Customer</a>.
648+
Hence any tax exemption that the <a>Customer</a> may enjoy when purchasing directly from the <a>Seller</a> (e.g. if the <a>Seller</a> is an [VAT exempt eligible body](https://www.gov.uk/guidance/sport-supplies-that-are-vat-exempt-notice-70145)) is not relevant here, as no direct contractual relationship is formed between <a>Seller</a> and <a>Customer</a>.
649649

650650
### Scope of Specification
651651
This specification is designed to govern the interaction between the `ResellerBroker` and <a>Seller</a>. It does include provision for the interaction between the `ResellerBroker` and <a>Customer</a> 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.
652-
When the brokerRole is set to `ResellerBroker`, this indicates that the payee for accounting and tax purposes is the "broker" specified in the Order.
652+
When the `brokerRole` is set to `ResellerBroker`, this indicates that the payee for accounting and tax purposes is the `broker` specified in the `Order`.
653653
Note that the `customer` may still optionally be included in the Order, for example to help front-of-house staff identify the <a>Customer</a>.
654654

655655
### Conformance criteria
@@ -674,7 +674,7 @@
674674

675675
### Taxation
676676
While facilitated by the `AgentBroker`, the primary purchase is made by the <a>Customer</a> directly from the <a>Seller</a>, as would be the case if the <a>Customer</a> was to purchase from the <a>Seller</a> independently.
677-
Hence any tax exception that the <a>Customer</a> may enjoy when purchasing directly from the <a>Seller</a> (e.g. if the <a>Seller</a> is an [VAT exempt eligible body](https://www.gov.uk/guidance/sport-supplies-that-are-vat-exempt-notice-70145)) is relevant here.
677+
Hence any tax exemption that the <a>Customer</a> may enjoy when purchasing directly from the <a>Seller</a> (e.g. if the <a>Seller</a> is an [VAT exempt eligible body](https://www.gov.uk/guidance/sport-supplies-that-are-vat-exempt-notice-70145)) is relevant here.
678678

679679
The <a>Customer</a>'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`.
680680

@@ -683,7 +683,7 @@
683683
### Scope of Specification
684684
This specification is designed to govern the recording of the execution of the contractual relationship between the <a>Customer</a> and <a>Seller</a>.
685685
The scope of this specification does not include the contractual relationship between the `AgentBroker` and the <a>Seller</a> (e.g. for booking commission), between the `AgentBroker` and the <a>Customer</a> (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.
686-
When the brokerRole is set to "AgentBroker", this indicates that the payee for accounting and tax purposes is the `customer` specified in the Order.
686+
When the `brokerRole` is set to `AgentBroker`, this indicates that the payee for accounting and tax purposes is the `customer` specified in the `Order`.
687687

688688
### Conformance criteria
689689
When the <a>Broker</a> generates the <a>Invoice</a>, it must be made payable to `Order.customer`, `Order.broker` MUST be provided and `Order.customer` MUST be provided.
@@ -706,13 +706,13 @@
706706

707707
### Taxation
708708
The purchase is made by the <a>Customer</a> directly from the <a>Seller</a>, as would be the case if the <a>Customer</a> was to purchase from the <a>Seller</a> outside of this specification.
709-
Hence any tax exception that the <a>Customer</a> may enjoy when purchasing directly from the <a>Seller</a> (e.g. if the <a>Seller</a> is an VAT exempt eligible body) is relevant here.
709+
Hence any tax exemption that the <a>Customer</a> may enjoy when purchasing directly from the <a>Seller</a> (e.g. if the <a>Seller</a> is an VAT exempt eligible body) is relevant here.
710710

711711
### Scope of Specification
712712
This specification is designed to govern the recording of the execution of the contractual relationship between the <a>Customer</a> and <a>Seller</a>.
713713
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.
714714

715-
When the brokerRole is set to "NoBroker", this indicates that the payee for accounting and tax purposes is the `customer` specified in the Order.
715+
When the `brokerRole` is set to `NoBroker`, this indicates that the payee for accounting and tax purposes is the `customer` specified in the `Order`.
716716

717717
### Conformance criteria
718718
When an <a>Invoice</a> is generated, it must be made payable to `Order.customer`, `Order.broker` MUST NOT be provided and `Order.customer` MUST be provided.
@@ -806,11 +806,14 @@
806806

807807
## Offer overrides
808808

809-
The unit price of an OrderItem may be overridden to allow for business models with dynamic or variable pricing.
809+
The unit price of an OrderItem may be overridden to allow for business models with variable pricing (where price differs from list price) and dynamic pricing (where price is not known at the point of purchase).
810810

811-
An `OfferOverride` type may be supplied to the `acceptedOffer` property at **C1**, **C2** and **B**. When an `OfferOverride` is used, it must be used consistently between **C2** and **B** to OrderQuote, it must be used by the booking system instead of acceptedOffer to calculate the tax and totals.
811+
An `OfferOverride` or `DynamicOffer` type may be supplied to the `acceptedOffer` property at **C1**, **C2** and **B**. When an `OfferOverride` or `DynamicOffer` is used, it must be used consistently between **C2** and **B** to OrderQuote, it must be used by the booking system instead of acceptedOffer to calculate the tax and totals.
812812

813-
The `unitTaxSpecification` is calculated by the booking system exactly as it would be for an standard `Offer`. The `price` of the `OfferOverride` may be zero, and also may be higher or lower than the available `Offer`s that exist in the <a>Booking System</a>.
813+
<div class="issue" data-number="96"></div>
814+
815+
### `OfferOverride`
816+
The `unitTaxSpecification` is calculated by the <a>Booking System</a> exactly as it would be for an standard `Offer`. The `price` of the `OfferOverride` may be zero, and also may be higher or lower than the available `Offer`s that exist in the <a>Booking System</a>.
814817

815818
`OfferOverride` MUST NOT be used when `isAccessibleForFree` is `true`, as free events cannot be overridden. Note that <a>Booking Systems</a> that only offer free opportunities MUST NOT implement `OfferOverride` support, and must always throw an error when it is used.
816819

@@ -824,7 +827,18 @@
824827
}
825828
</pre>
826829

827-
<div class="issue" data-number="96"></div>
830+
### `DynamicOffer`
831+
The `DynamicOffer` MUST NOT include a `price`, and MUST NOT contribute to the `totalPaymentDue` of the `Order`. `unitTaxSpecification` MUST NOT be calculated by the <a>Booking System</a> for a `DynamicOffer`.
832+
833+
The `identifier` of the `DynamicOffer` MUST be used consistently in order to allow the Seller to reconcile opportunities booked using a particular type of `DynamicOffer` out-of-band.
834+
835+
<pre class="example" title="Example of DynamicOffer">
836+
"acceptedOffer": {
837+
"type": "DynamicOffer",
838+
"name": "MoveGB Membership"
839+
"identifier": "MOVE"
840+
}
841+
</pre>
828842

829843

830844
</section>
@@ -844,7 +858,7 @@
844858

845859
An opportunity of type `Event`, `ScheduledSession`, `HeadlineEvent`, `Slot` or `CourseInstance` is deemed to be <dfn>bookable</dfn> via the Open Booking API if:
846860

847-
- `availableChannel` of a valid `Offer` includes `https://openactive.io/OpenBookingPrepayment`.
861+
- `availableChannel` of a valid `Offer` (that is not an `IndicativeOffer`) includes `https://openactive.io/OpenBookingPrepayment`.
848862

849863
- The `endDate` is not already in the past (note that bookings are still possible after the `startDate`).
850864

@@ -879,11 +893,34 @@
879893
4. The <a>Broker</a> MUST then filter this applicable set to provide a set of `Offers` which are current (based on `validFromBeforeStartDate`) and are available to the <a>Customer</a> through the <a>Broker</a> (based on `availableChannel`).
880894
5. The <a>Broker</a> MAY additionally filter based on the `Offer`s that apply to the customer, for example based on `ageRange` if specified in the `Offer`. This specification provides no guidance as to how the filtering should be performed, however it recommends against gathering additional personal data about the <a>Customer</a> in order to restrict `Offer`s presented, and instead advocates clear messaging regarding the restrictions of each `Offer` to allow the <a>Customer</a> to make an informed decision.
881895

896+
Note that `IndicativeOffer`s are ignored for the algorithm above, and are not considered bookable.
882897

883898

884899
<div class="issue" data-number="103"></div>
885900

886901

902+
### `IndicativeOffer`
903+
904+
There are cases where `Offer`s are provided at the `SessionSeries` or `FacilityUse` level which are indicative, and are not intended to be inherited and applied to the `ScheduledSession`s or `Slot`s within them. For such cases an `IndicativeOffer` may be used to indicate that the offer must not be considered bookable.
905+
906+
<pre class="example" title="Example of IndicativeOffer">
907+
"offers": [
908+
{
909+
"type": "IndicativeOffer",
910+
"name": "Off Peak",
911+
"price": 7.00,
912+
"priceCurrency": "GBP"
913+
},
914+
{
915+
"type": "IndicativeOffer",
916+
"name": "Peak",
917+
"price": 10.00,
918+
"priceCurrency": "GBP"
919+
}
920+
]
921+
</pre>
922+
923+
887924
## Amending the OrderQuote before **B**
888925

889926
The <a>Broker</a> MAY call **C1** and MUST call **C2** when the <a>Customer</a> updates their basket to add and remove items.
@@ -1425,6 +1462,41 @@
14251462

14261463
Note that for an `Offer` to be bookable under this specification, `availableChannel` must include `https://openactive.io/OpenBookingPrepayment`.
14271464

1465+
1466+
### `schema:OfferOverride`
1467+
1468+
`OfferOverride` subclasses `Offer`.
1469+
1470+
| Property | Broker Request | Booking System Response | Type | Notes |
1471+
|--------------------------------------------------------------------|----------|----------|-|------|
1472+
| `@type` | REQUIRED | REQUIRED | [`schema:Text`](https://schema.org/Text) | `Offer` |
1473+
| `@id` | REQUIRED | REQUIRED | [`schema:URL`](https://schema.org/URL) | A URI providing a unique identifier for the Offer |
1474+
| [`schema:price`](http://schema.org/price) | REQUIRED | REQUIRED | [`schema:Float`](https://schema.org/Float) | The offer price available to participants, which includes or excludes tax depending on the `taxMode` of the `Order`. |
1475+
| [`schema:priceCurrency`](http://schema.org/priceCurrency) | REQUIRED | REQUIRED | [`schema:Text`](https://schema.org/Text) | The currency of the `price`. Specified as a 3-letter ISO 4217 value. If a `PriceSpecification` has a zero `price`, then this property is not required. Otherwise the `priceCurrency` MUST be specified. |
1476+
| [`schema:name`](http://schema.org/name) | RECOMMENDED | RECOMMENDED | [`schema:Text`](https://schema.org/Text) | The name of the offer suitable for display to participants. |
1477+
| [`oa:availableChannel`](https://openactive.io/availableChannel) | - | - | - | Not included in `OfferOverride`. |
1478+
| [`oa:validFromBeforeStartDate`](https://openactive.io/validFromBeforeStartDate) | OPTIONAL | OPTIONAL | [`schema:Duration`](https://schema.org/Duration) | The duration before the `startDate` for which this Offer is valid, given in [ISO8601] format. This is a relative equivalent of [`schema:validFrom`](http://schema.org/validFrom), to allow for Offer inheritance. |
1479+
| [`oa:latestCancellationBeforeStartDate`](https://openactive.io/latestCancellationBeforeStartDate) | OPTIONAL | OPTIONAL | [`schema:Duration`](https://schema.org/Duration) | The duration before the `startDate` during which this Offer may **not** be cancelled, given in [ISO8601] format. |
1480+
1481+
1482+
### `schema:DynamicOffer`
1483+
1484+
`DynamicOffer` subclasses `Offer`.
1485+
1486+
| Property | Broker Request | Booking System Response | Type | Notes |
1487+
|--------------------------------------------------------------------|----------|----------|-|------|
1488+
| `@type` | REQUIRED | REQUIRED | [`schema:Text`](https://schema.org/Text) | `Offer` |
1489+
| [`schema:identifier`](http://schema.org/identifier) | REQUIRED | REQUIRED | [`schema:Text`](https://schema.org/Text) | Used consistently in order to allow the Seller to reconcile opportunities booked using a particular type of `DynamicOffer` out-of-band. |
1490+
| [`schema:name`](http://schema.org/name) | RECOMMENDED | RECOMMENDED | [`schema:Text`](https://schema.org/Text) | The name of the offer suitable for display to participants. |
1491+
| [`oa:validFromBeforeStartDate`](https://openactive.io/validFromBeforeStartDate) | OPTIONAL | OPTIONAL | [`schema:Duration`](https://schema.org/Duration) | The duration before the `startDate` for which this Offer is valid, given in [ISO8601] format. This is a relative equivalent of [`schema:validFrom`](http://schema.org/validFrom), to allow for Offer inheritance. |
1492+
| [`oa:latestCancellationBeforeStartDate`](https://openactive.io/latestCancellationBeforeStartDate) | OPTIONAL | OPTIONAL | [`schema:Duration`](https://schema.org/Duration) | The duration before the `startDate` during which this Offer may **not** be cancelled, given in [ISO8601] format. |
1493+
| [`schema:price`](http://schema.org/price) | - | - | - | Not included in `DynamicOffer`. |
1494+
| [`schema:priceCurrency`](http://schema.org/priceCurrency) | - | - | - | Not included in `DynamicOffer`. |
1495+
| [`oa:availableChannel`](https://openactive.io/availableChannel) | - | - | - | Not included in `OfferOverride`. |
1496+
1497+
1498+
1499+
14281500
### `schema:Person`
14291501

14301502
For business-to-consumer transactions, the `customer` MUST be a `schema:Person`.
@@ -1522,6 +1594,9 @@
15221594
| `@type` | - | REQUIRED | [`schema:Text`](https://schema.org/Text) | `Payment` |
15231595
| [`schema:name`](http://schema.org/name) | - | OPTIONAL | [`schema:Text`](https://schema.org/Text) | Optional free text description of the payment method for the <a>Booking System</a>, to help the <a>Seller</a> in discussions with the <a>Customer</a> (e.g. "AcmeBroker Points" or "AcmeBroker via Credit Card") |
15241596
| [`schema:identifier`](http://schema.org/identifier) | - | REQUIRED | [`schema:Text`](https://schema.org/Text) | The identifier of the payment held by the <a>Broker</a> and/or <a>Payment Provider</a>. |
1597+
| [`schema:paymentMethod`](http://schema.org/paymentMethod) | - | REQUIRED | [`schema:PaymentMethod`](https://schema.org/PaymentMethod) | If using the payment extension point, this references the payment method used. If not present indicates the external payment processor. |
1598+
| [`schema:accountId`](http://schema.org/accountId) | - | OPTIONAL | [`schema:Text`](https://schema.org/Text) | A reference used by the <a>Seller</a> to group transactions, which is used to aid reconciliation. |
1599+
15251600

15261601
Note that `identifier` and are NOT REQUIRED if `paymentMethod` is specified, to maximise flexibility of the payments extension point.
15271602

0 commit comments

Comments
 (0)