Offerings catalog

Yield Rules

A YieldRule adjusts an offering's price according to how busy the site is, on top of the offering's existing price rules and within its yield price guardrails.

The YieldRule object

Attributes

  • iduuidrequired
  • offering_typestringrequired

    The kind of offering a rule applies to. Limited to offerings booked against a service date, which is what demand is measured over.

    Possible values:appointmentarea_bookingsessionpackage
  • offering_iduuidrequired

    The offering this rule adjusts the price of.

  • site_iduuidrequired
  • created_batch_iduuidrequirednullable

    Shared by every rule created in the same request. The rules remain independent of one another — editing one does not affect the others — so this only records that they were created together.

  • weekdaysstring[]required

    The days of the week this rule applies on.

  • time_fromstringrequirednullable

    Start of the daily window this rule applies within, in the site's local time. 24-hour HH:MM. Each selected weekday is the day its window starts on. Null alongside a null time_to means the rule applies all day.

  • time_tostringrequirednullable

    End of the daily window this rule applies within, in the site's local time. 24-hour HH:MM. A value earlier than time_from means the window runs past midnight into the following day. Null alongside a null time_from means the rule applies all day.

  • triggersobjectrequired

    The demand conditions under which a rule fires.

    At least one band must be set. When both are set the rule fires if either is satisfied, so setting both widens a rule rather than narrowing it.

  • adjustmentobjectrequired

    The change a rule makes to the price it applies to. Signed, so a rule can discount to shift demand as well as add a premium at peak.

  • roundingstringrequirednullable

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

    Possible values:onefiveten
  • reporting_tierstringrequired

    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.

    Possible values:lowhighpeak
  • created_atdate-timerequired
  • updated_atdate-timerequired

    When several rules could apply to the same slot, the most recently updated one wins.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "offering_type": "appointment",
  "offering_id": "00000000-0000-0000-0000-000000000000",
  "site_id": "00000000-0000-0000-0000-000000000000",
  "created_batch_id": "00000000-0000-0000-0000-000000000000",
  "weekdays": [
    "monday"
  ],
  "time_from": "12:00",
  "time_to": "21:00",
  "triggers": {
    "practitioner_utilisation": "string",
    "room_occupancy": {
      "from": 70,
      "to": 90
    }
  },
  "adjustment": {
    "type": "amount",
    "value": 15
  },
  "rounding": "one",
  "reporting_tier": "low",
  "created_at": "2026-01-15T09:30:00+00:00",
  "updated_at": "2026-01-15T09:30:00+00:00"
}
get/shop/yield-rules

List YieldRules

listYieldRules

Lists the YieldRules configured for a site.

Pass offering_type and offering_id together to narrow the list to the rules affecting one offering, or created_batch_id to return only the rules created by a single request.

Requires the advanced_yield_management feature. Sites without it return 404, since yield rules do not exist as a concept for them.

Query parameters

  • site_iduuidrequired

    The site whose yield rules to list.

  • offering_typestringoptional

    Narrow the list to one offering, alongside offering_id. Both are needed together, since an ID alone does not identify the kind of offering.

    Possible values:appointmentarea_bookingsessionpackage
  • offering_iduuidoptional

    Narrow the list to one offering, alongside offering_type.

  • created_batch_iduuidoptional

    Narrow the list to the rules created by one request. Used to follow a create that was answered with 202 and handed off to a background job.

  • pageintegeroptional

    The page to retrieve results from

  • per_pageintegeroptional

    The number of results to return per page

Responses

  • 200

    The yield rules were successfully retrieved

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

post/shop/yield-rules

Create YieldRules

createYieldRules

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.

Request body

  • site_iduuidrequired

    The site the rules belong to.

  • offeringsobject[]required

    The offerings to apply this rule to. One independent rule is created for each, so editing one afterwards does not affect the others. Repeating an offering creates a single rule for it.

    Each offering must belong to site_id and have a standard price for the adjustment to work from, and they must all share one offering_type — a single rule cannot span types, because what a rule may contain differs between them.

    More than 200 offerings are created by a background job and answered with 202.

  • weekdaysstring[]required
  • time_fromstringrequirednullable

    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_tostringrequirednullable

    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:3000:30 runs Monday 22:30 to Tuesday 00:30. Send null for both this and time_from for a rule that applies all day.

  • triggersobjectrequired

    The demand conditions under which a rule fires.

    At least one band must be set. When both are set the rule fires if either is satisfied, so setting both widens a rule rather than narrowing it.

  • adjustmentobjectrequired

    The change a rule makes to the price it applies to. Signed, so a rule can discount to shift demand as well as add a premium at peak.

  • roundingstringoptionalnullable

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

    Possible values:onefiveten
  • reporting_tierstringrequired

    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.

    Possible values:lowhighpeak
  • 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.

Responses

  • 201

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

  • 202

    The selection was too large to write during the request, so the rules are being created by a background job. Poll the list endpoint with created_batch_id to follow them appearing.

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

get/shop/yield-rules/{yieldRule}

Get a YieldRule

getYieldRule

Retrieves a single YieldRule.

Path parameters

  • yieldRuleuuidrequired

    The ID of the yield rule.

Responses

  • 200

    The yield rule was successfully retrieved

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

put/shop/yield-rules/{yieldRule}

Update a YieldRule

updateYieldRule

Replaces this rule's definition in full.

Only this rule changes. Rules created alongside it are independent copies and are left untouched, and the offering a rule applies to is fixed at creation.

When reductions may start is not part of the rule and cannot be changed here. That window belongs to the offering and is shared by every rule lowering its price, so it is set when a rule is created and changed from the offering.

Path parameters

  • yieldRuleuuidrequired

    The ID of the yield rule.

Request body

  • weekdaysstring[]required
  • time_fromstringrequirednullable

    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_tostringrequirednullable

    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:3000:30 runs Monday 22:30 to Tuesday 00:30. Send null for both this and time_from for a rule that applies all day.

  • triggersobjectrequired

    The demand conditions under which a rule fires.

    At least one band must be set. When both are set the rule fires if either is satisfied, so setting both widens a rule rather than narrowing it.

  • adjustmentobjectrequired

    The change a rule makes to the price it applies to. Signed, so a rule can discount to shift demand as well as add a premium at peak.

  • roundingstringrequirednullable

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

    Possible values:onefiveten
  • reporting_tierstringrequired

    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.

    Possible values:lowhighpeak

Responses

  • 200

    The yield rule was successfully retrieved

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

delete/shop/yield-rules/{yieldRule}

Delete a YieldRule

deleteYieldRule

Deletes a YieldRule. Rules created alongside it are unaffected.

Path parameters

  • yieldRuleuuidrequired

    The ID of the yield rule.

Responses

  • 204

    The yield rule was successfully deleted

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found