Wakato Pass

Tools in the pass scope, callable over space-mcp (tools/call) or space-api (REST) with a wks_live_* key that grants pass.

adjust_pass_balance

Scope: pass:write

Add or deduct on a customer's card. balance: 'points' (points or stamps, the default) or 'gift_value' (money — load it with a positive delta, spend with a negative one). Target by install_id, or by template_id + contact_email/contact_id. Never below zero. Lands in the pass ledger like every other change; a points change fires 'balance reaches' automations.

cancel_pass_entry

Scope: pass:write

Take back an entry a holder has (entry_id from list_pass_holders).

create_pass_template

Scope: pass:write

Create a Wakato Pass — ONE card a customer adds to their account via the returned /card/<code> link (or is given with grant_pass_card, or by an automation's enroll_in_pass step). Say what it does — any combination, changeable later with update_pass_template: earn (points or stamps), membership, gift_value, next_booking — or nothing yet (a name and a description is a pass; what it unlocks can come after). Membership tiers each have their own length in config.tier_days {tier: days, 0 = never ends}; perks every holder has are config.perks [{kind:'discount', name, style:'percent'|'amount', value, applies_to} | {kind:'content', name, body}]; buttons every holder can tap (on the card page and in Apple/Google Wallet, ≤6) are config.buttons [{kind:'url'|'booking'|'listing'|'phone'|'whatsapp'|'email', label, value}] — value = the https address, a booking page id, a listing id, a phone number with country code or an email; an entry with on_join:true is given to every new holder. A salon with points, a membership and gift value is one card, not three. A pass needs no community. Earn rules: earn_per_scan awards on a staff scan at the till (a door never earns); for anything else (e.g. +10 points per booking) create an automation with the adjust_pass_balance action. Starts as draft — set status:'active' (or update later) to make it installable.

get_pass_card_design

Scope: pass:read

How a pass's card looks in Apple and Google Wallet: its design (colours, typed name or logo, the banner's layers, the scan code, what the front says), a link to the banner as it looks now, the designs you can start from, and how every part works. Read it before changing the look.

get_pass_template

Scope: pass:read

Get one pass template with its config, rewards, active holder count, and the public install link (/card/<code>) customers use to add the card.

give_pass_entry

Scope: pass:write

Give a card holder an ENTRY: a ticket (type_key: one of the entry's types, e.g. vip or table_of_4), a class pack, a day pass, a place. entry_key names one of the pass's entries (get_pass_template shows them). Target by install_id, or template_id + contact_email/contact_id. people/uses/valid_from/valid_until override the entry's settings for this one.

grant_pass_card

Scope: pass:write

Give someone a card — the way to enroll a person who did not scan the sign-up code themselves. On a card_only pass (holder_mode) the card is made and its link sent by email, or by a text from the space's number when there is only a phone (billed like any text); they keep it in their phone's wallet, no account needed → outcome card_sent | card_sent_again (installed/already_held when that email is already a Wakato account). On an account pass it is an offer: a Wakato account gets it as PENDING to accept; anyone else is emailed a sign-up link → pending | installed | already_held | invited | invite_already_sent. The pass must be ACTIVE.

list_pass_holders

Scope: pass:read

List customers holding cards in this space (joined with their contact name/email), with balance (points or stamps), stored_value (gift value), tier, validity, and their answers to the pass's joining questions. Optional template_id filter.

list_pass_places

Scope: pass:read

The places this space scans Wakato Pass cards at (the front counter, a door, a festival gate) and, for each, what staff see (show, in order), the stop signs (red = don't let in, amber = look twice), what staff and managers may do (limits: points_max, gift_max, override, undo_minutes) and the briefing on the scanner.

list_pass_templates

Scope: pass:read

List the space's Wakato Pass templates — the cards customers add to their account (loyalty points, stamp cards, memberships, gift value, next booking; one card can do several). Each carries earn, has_membership, has_stored_value (gift value), has_booking and headline. Call before create_pass_template to reuse an existing one.

review_pass_holder

Scope: pass:write

Approve or refuse a holder waiting on a pass that approves each one (approve_holders on; list_pass_holders shows approval 'waiting'). A waiting card doesn't work at the scan until approved.

review_pass_photo

Scope: pass:write

Approve or refuse the photo on a card, when the pass has photos checked before the card works (list_pass_holders shows photo_status 'pending'). Refusing needs a note — the holder reads it and sends a new one.

save_pass_place

Scope: pass:write

Create or change a place the space scans cards at (place_id to change one). { name, mode: 'till' (counter: points, rewards, gift value) | 'door' (membership check) | 'entry' (let in and count on an entry: entry_key names the pass's entry) | 'event' (a community event: event_id), show: [{key, on}] in order (photo, entry, tags, answers, visits, note, membership, points, gift, rewards, next_booking, birthday), stop_signs: [{key, on, age?}] (already_in, not_now, used_up, no_entry, membership_ended, frozen, photo_pending, under_age) plus your own [{key:'custom_1', on, custom:{level:'red'|'amber', title, when:{kind:'tag', tag} | {kind:'answer', question, equals?} | {kind:'gift_below', amount} | {kind:'points_above', amount}}}], limits: {staff:{override, points_max, gift_max, undo_minutes}, managers:{...}}, briefing, buttons: [{key, label, who:'everyone'|'managers', when:'always'|'stop'|'clear', ask}] — the owner's OWN buttons under every scan answer here (e.g. 'Ask for help'; up to 6; ask = a line staff type first, or null). What a button does is automations on the trigger pass_scan_button_pressed filtered by button_key; a button nothing listens to is not shown. Keep each existing button's key when you change it. }. Anything left out gets the place's defaults — except buttons, which stay as they are when left out.

sell_pass_gift_card

Scope: pass:write

Sell the pass's gift value as a gift card of one amount (at least 5): makes a LIVE Commerce listing of the shop run from this space and the automation that, when it is paid, gives the buyer the card and puts the amount on it. stop_product_id takes one off sale instead. The pass needs gift_value on and the space a Commerce account.

sell_pass_unlock

Scope: pass:write

Sell a membership tier or an entry (a ticket, a class pack, a day pass…) straight from a pass: makes a LIVE Commerce listing of the shop run from this space and the automations that give it to the buyer — the card too if they don't hold it. unlock = {kind:'tier', tier} (one of config.tiers) or {kind:'entry', entry_key, type_key?} (one of the pass's entries). billing one_time | monthly | yearly (monthly/yearly only for a membership: renewals extend it, the subscription ending ends it; on_fail 'now' also ends it the moment a payment fails, 'period' (default) lets the paid time run out). stop_product_id takes one off sale instead. What is on sale is in the pass's config.sales.

set_pass_card_design

Scope: pass:write

Design how a pass's card looks in Apple and Google Wallet: start from one of Wakato's designs (start_from: wellness, coffee, membership, gift, ticket, salon, neon, barber, bakery, yoga, florist, carwash, winebar, playcentre, cowork, surf, pets, books, blank — the business's name and initials go on it), then change what the business wants: colours, the typed name or an uploaded logo, a background photo (photo_url; null removes it), the banner's layers (shapes, patterns, stamps, words, pictures), the scan code (wallet's own, branded in the business's colours, or none), and what the front says (top, big, under, appointmentFirst). Each part sent is merged over the current design; send design to replace it whole. Every card already in a wallet redraws. Answers with banner_url — look at it to check your work. get_pass_card_design explains every part.

set_pass_note

Scope: pass:write

Pin the team's note on a card holder (staff see it at the scan, e.g. “Prefers the window table”). An empty note removes it.

start_pass_grant_automation

Scope: pass:write

Grant something on a pass when something happens: makes ONE automation of the space, switched OFF, with the trigger and the steps filled in (Give Pass Card, then what it gives). unlock = {kind:'pass'} (the card itself), {kind:'tier', tier}, {kind:'entry', entry_key, type_key?}, {kind:'points'} or {kind:'gift_value'}. trigger_type one of booking_submission, form_submission, community_member_joined, commerce_order_paid, tag_added, pass_balance_reached, pass_scanned. Finish the trigger's settings (which form, which tag…) with the automation tools, then switch it on.

update_pass_template

Scope: pass:write

Edit a pass: what it does (earn points/stamps/none, membership, gift_value, next_booking, headline — send only what changes; switching points<->stamps is refused while anyone holds a balance, and gift_value can't be switched off while anyone holds money; switching anything else off hides nothing people hold for good), rules (earn_per_scan, scan_cooldown_minutes, config), rewards (replaces the whole array), join_fields (replaces the whole array), brand, description, or status (draft/active/archived — archived cards stop scanning).