Sign in
YieldRules

Create YieldRules

Creates a YieldRule for each offering supplied.

Rules are per-offering. Applying one definition to several offerings is a convenience at creation only: it produces an independent rule for each, so editing or deleting one afterwards leaves the rest untouched, and offerings created later do not pick the rule up.

Every offering must belong to the site and have a standard price for the adjustment to work from, and they must all be the same offering_type: what a rule may contain differs between types, since an appointment has a practitioner to measure utilisation against and an area booking type does not. If any offering is rejected, no rules are created.

Selections of more than 200 offerings are written by a background job and answered with 202 and the created_batch_id the rules will carry, rather than holding the response open for several seconds. Poll the list endpoint with that id to follow them appearing.

A rule that lowers a price needs the offering to say when reductions may start. Send reduction_advance_interval to set that window on every offering the rule is created for, or leave it out where they are already configured. Creating a rule is the only time it can be set through this resource; changing it afterwards is done from the offering.

Requires the advanced_yield_management feature and the same permission as editing an offering's price rules.

post/shop/yield-rules

Request body

site_idstring uuid required

The site the rules belong to.

weekdaysWeekday[] required
time_fromstring nullable required

24-hour HH:MM, in the site's local time. Send null for both this and time_to for a rule that applies all day; one without the other is rejected.

time_tostring nullable required

24-hour HH:MM, in the site's local time. Must differ from time_from. An earlier value means the window runs past midnight into the following day, and each selected weekday is the day its window starts on — Monday with 22:30–00:30 runs Monday 22:30 to Tuesday 00:30. Send null for both this and time_from for a rule that applies all day.

rounding'one' | 'five' | 'ten' nullable

Rounds the adjusted price to the nearest whole unit of currency. null leaves the adjusted price unrounded.

reporting_tier'low' | 'high' | 'peak' required

Groups yielded sales in reporting. Descriptive only — it never affects the adjustment a rule makes. Sales made when no rule applied report as an implicit standard tier, which is why it is absent here. The yielded sales report lists and totals sales by this tier.

reduction_advance_intervalstring

How far ahead of a slot a rule that lowers the price may start applying, as an ISO-8601 duration.

The window belongs to the offering rather than the rule: every rule that lowers an offering's price shares the one window. Sending it here sets it on all of the offerings the rule is being created for, overwriting whatever each already had, so a value set from one offering can be replaced by a rule created across many.

A rule that lowers a price cannot exist on an offering with no window, so one must either be sent here or already be configured on every offering listed. Rules that raise a price ignore the window and need not send it.

Omit the key to leave each offering's window as it is. It cannot be sent empty: a window is taken away from the offering itself, where the check that no rule still depends on it lives.

Example request

{
  "time_from": "12:00",
  "time_to": "21:00",
  "triggers": {
    "practitioner_utilisation": {
      "from": 70,
      "to": 90
    },
    "room_occupancy": {
      "from": 70,
      "to": 90
    }
  },
  "adjustment": {
    "value": 15
  },
  "reduction_advance_interval": "P2D"
}

Response

The yield rules were successfully created. One rule is returned per offering supplied, each independent of the others.

Example response

{
  "data": [
    {
      "time_from": "12:00",
      "time_to": "21:00",
      "triggers": {
        "practitioner_utilisation": {
          "from": 70,
          "to": 90
        },
        "room_occupancy": {
          "from": 70,
          "to": 90
        }
      },
      "adjustment": {
        "value": 15
      }
    }
  ]
}

Changes