To let an assistant use these tools, grant Insurance operations on the consent screen, or just
Loyalty programmes under its Fine-tune. The scope is loyalty.
Read tools work with Read only or Read & write access; write tools only with
Read & write.
Your assistant doesn't see these tools straight away. It finds them with search_tools or
describe_tools, and runs one with use_tool, passing its name and
arguments. Most assistants do this for you: just ask for what you want.
What your assistant is told about this group
Loyalty programmes that run alongside policies: each programme's settings (tiers, whether Subcontext or an outside provider works out points and tiers, and premium flex), its points rules (when Subcontext works out the points) and its members, with their history of points and tiers. award_loyalty_points and transition_loyalty_member change a real customer's membership: confirm with the user first. To attach a programme to a product, use set_product_loyalty_programme (products group).
The descriptions below are the ones your assistant reads, so they're written for it. When a connection covers more than one
organisation, the assistant passes org (the organisation's slug, from list_orgs) to say which one.
list_loyalty_programmes
Read List loyalty programmes
The org's loyalty programmes with their attached products and member counts.
Arguments
| Field | Type | Description |
|---|---|---|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_loyalty_programme
Read Get a loyalty programme
One programme's full configuration (tiers, premium flex), its product attachments, points rules, member count and the 100 most recent members.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | Programme id |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
create_loyalty_programme
Write Create a loyalty programme
Create a loyalty programme. Attach it to a product with set_product_loyalty_programme; native-mode programmes award points through their points rules.
Arguments
| Field | Type | Description |
|---|---|---|
| name required | string | |
| slug required | string | Lowercase letters, digits and hyphens; unique in the org |
| engine_mode | string |
external: a partner asserts points and tiers. native: computed here from the tier thresholds
One of: "external", "native"
|
| cycle_anchor | string |
When each member's points year starts and resets
One of: "policy_anniversary", "calendar_year"
|
| lifecycle_state | string |
Production products can only attach production programmes
One of: "draft", "sandbox", "production", "archived"
|
| fee_pence | integer | Programme fee per member per month, in pence (0 = free) |
| initial_discount_pct | string | Starting premium discount percent, e.g. "5.0" |
| tiers | array of object | Tier ladder, ascending by threshold |
| tiers[].key | string | |
| tiers[].name | string | |
| tiers[].threshold_points | integer | |
| premium_flex | object | Premium discount percent by tier key, e.g. {"gold": 5} |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
update_loyalty_programme
Write Update a loyalty programme
Update a programme's configuration. Only supplied attributes change. Tier and flex changes affect every existing member, so confirm with the user first.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | Programme id |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
| name | string | |
| slug | string | Lowercase letters, digits and hyphens; unique in the org |
| engine_mode | string |
external: a partner asserts points and tiers. native: computed here from the tier thresholds
One of: "external", "native"
|
| cycle_anchor | string |
When each member's points year starts and resets
One of: "policy_anniversary", "calendar_year"
|
| lifecycle_state | string |
Production products can only attach production programmes
One of: "draft", "sandbox", "production", "archived"
|
| fee_pence | integer | Programme fee per member per month, in pence (0 = free) |
| initial_discount_pct | string | Starting premium discount percent, e.g. "5.0" |
| tiers | array of object | Tier ladder, ascending by threshold |
| tiers[].key | string | |
| tiers[].name | string | |
| tiers[].threshold_points | integer | |
| premium_flex | object | Premium discount percent by tier key, e.g. {"gold": 5} |
delete_loyalty_programme
Write Delete a loyalty programme
Permanently delete a programme, its product attachments and points rules. Refused while the programme has members. Confirm with the user first.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | Programme id |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
create_loyalty_points_rule
Write Add a points rule
Add a points rule to a native-mode programme: monthly (at each membership month), anniversary (into each new cycle), enrolment (one-off welcome bonus) or policy_event (when a policy event fires; needs event_key). Rules award points to real members automatically, so confirm with the user first.
Arguments
| Field | Type | Description |
|---|---|---|
| programme_id required | string | |
| trigger required | string |
One of: "monthly", "anniversary", "enrolment", "activity", "policy_event"
|
| points required | integer | Non-zero |
| label required | string | Shown on the member's ledger |
| event_key | string |
policy_event rules only
One of: "premium.first_collected", "premium.collected", "policy.bound_locally"
|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
delete_loyalty_points_rule
Write Remove a points rule
Remove a points rule from its programme. Points already awarded stay on members' ledgers.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | Points rule id |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_loyalty_members
Read List loyalty members
Programme members across the org, newest first. Filter by programme and status; q searches partner member ref, policy number and customer name/email.
Arguments
| Field | Type | Description |
|---|---|---|
| programme_id | string | |
| status | string |
One of: "pending", "active", "suspended", "cancelled"
|
| q | string | Free-text search |
| limit | integer | Max rows (1-100, default 25) |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_loyalty_member
Read Get a loyalty member
One programme member: status, tier, cycle points, their full points/tier ledger and programme event timeline (both newest first).
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | Membership id |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
award_loyalty_points
Write Award loyalty points
Award (positive) or correct (negative) a member's points on a native-mode programme, attributed to you. This changes a real customer's points balance and can move their tier. Confirm the member, amount and reason with the user before calling. External-mode programmes are refused: the partner owns their points.
Arguments
| Field | Type | Description |
|---|---|---|
| membership_id required | string | |
| points required | integer | Non-zero; negative for a correction |
| reason | string | Recorded on the ledger entry |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
transition_loyalty_member
Write Change a loyalty member's status
Move a member through the programme workflow: active approves a pending member (needs external_member_ref unless one is stored) or resumes a suspended one; suspended pauses an active member; cancelled ends the membership. This changes a real customer's membership, so confirm with the user before calling.
Arguments
| Field | Type | Description |
|---|---|---|
| membership_id required | string | |
| status | string |
One of: "active", "suspended", "cancelled"
|
| external_member_ref | string | The partner's member reference |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |