Customer Messages
A message plan is the set of emails and texts a customer receives around a booking. Plans exist at four levels, and the most specific one wins:
| Level | scope | Applies to |
|---|---|---|
| A program | item, owner program | bookings on that program |
| One item | item, owner product / experience / bundle | bookings containing that item |
| A line of business | rentals · experiences · bundles | every booking of that kind |
| Everything | all | every booking — the default everything falls back to |
The rule
The most specific one wins.
Resolution happens per booking line, not per booking. A rental and a guided session sold together are two different journeys and legitimately resolve to two different plans, so one booking can draw on several.
Two things follow from that, and both are handled for you:
- The same plan resolved twice is scheduled once. Two rentals on one booking both follow the rentals plan; its messages go out once.
- The same message from two plans reaches a person once. If both the rentals plan and the experiences plan carry a "Know before you go", the customer receives it a single time.
The resolved chain
Every item endpoint reports the chain it resolved through, with the winner marked — so an integration never has to reimplement the precedence to know what a customer will actually get.
"chain": [
{ "level": "item", "label": "Touring kayak", "plan_id": null, "exists": false, "winner": false },
{ "level": "rentals", "label": "Rentals", "plan_id": 8, "exists": true, "winner": true },
{ "level": "all", "label": "All bookings", "plan_id": 3, "exists": true, "winner": false }
]
Authentication
| Endpoints | Scope |
|---|---|
/v1/message-plans (all scopes) | settings:read / settings:write |
/v1/products/{id}/message-plan | products:read |
/v1/experiences/{id}/message-plan | experiences:read |
/v1/bundles/{id}/message-plan | bundles:read |
| A program's own plan | series:read / series:write — see Program Messages |
The shop-wide and line-of-business plans are shop settings, so they use settings:*. An item's plan is read through the item's own scope: whoever can see the product can see what it sends.
The message shape
A message on a plan uses exactly the same fields as a program message — channel, audience, timing, subject, blocks. Session-based anchors (each_session, session_number) only mean anything on a program's plan; everywhere else use the booking-shaped ones.