@open-loyalty/mcp-server 1.3.7 → 1.4.1

package/dist/instructions.d.ts

@@ -2,4 +2,4 @@
  * MCP Server Instructions - provides context and guidance for AI agents
  * using the Open Loyalty MCP server.
  */
-export declare const SERVER_INSTRUCTIONS = "\nOpen Loyalty MCP Server - Complete Loyalty Program Management\n\n## Domain Model\n\nMember (loyalty program participant)\n  \u2514\u2500\u2500 Points (wallet balance, transfers)\n  \u2514\u2500\u2500 Tier (current level: Bronze, Silver, Gold)\n  \u2514\u2500\u2500 Transactions (purchase history)\n  \u2514\u2500\u2500 Rewards (redeemed coupons)\n  \u2514\u2500\u2500 Achievements (gamification progress)\n  \u2514\u2500\u2500 Badges (visual rewards from achievements)\n\nTierSet (loyalty program structure)\n  \u2514\u2500\u2500 Conditions (criteria: activeUnits, totalSpending)\n  \u2514\u2500\u2500 Tiers (levels with thresholds)\n\nWalletType (points currency configuration)\n\nReward (redeemable items)\n  \u2514\u2500\u2500 Categories (reward groupings)\n\nCampaign (automated points/rewards rules)\n  \u2514\u2500\u2500 Type (earning, spending, custom, instant_reward)\n  \u2514\u2500\u2500 Trigger (transaction, custom_event, points_transfer)\n  \u2514\u2500\u2500 Rules (SKU, category, transaction amount conditions)\n  \u2514\u2500\u2500 Effects (give_points, multiply_points, percentage_discount)\n  \u2514\u2500\u2500 Targeting (segments, tiers for audience)\n\nSegment (member audience grouping)\n  \u2514\u2500\u2500 Parts (groups of criteria - OR logic between parts)\n      \u2514\u2500\u2500 Criteria (conditions - AND logic within part)\n          Types: transaction_count (working; requires min+max). Other types may be rejected by the API.\n\nAchievement (gamification goals)\n  \u2514\u2500\u2500 Trigger (transaction, custom_event, points_transfer, reward_redemption, referral, achievement, tier_change, profile_update)\n  \u2514\u2500\u2500 CompleteRule (periodGoal, period type, unique counting)\n  \u2514\u2500\u2500 Badge (visual reward when completed)\n\nBadge (visual recognition)\n  \u2514\u2500\u2500 Linked to achievements via badgeTypeId\n  \u2514\u2500\u2500 Auto-created when referenced by achievement\n\n## Key Workflows\n\n### 1. Create 3-tier Loyalty Program:\nRECOMMENDED WORKFLOW:\n1. wallet_type_list \u2192 Get wallet code (usually \"default\")\n2. tierset_list \u2192 Check if tier set already exists\n3. IF EXISTS: tierset_get \u2192 Get conditionId from existing tier set\n   ELSE: tierset_create \u2192 Create new, then tierset_get to get conditionId\n4. tierset_update_tiers \u2192 Define tier thresholds using conditionId\n5. tierset_get_tiers \u2192 Verify tiers created correctly\n\nGOTCHA - Valid tier condition attributes:\n- activeUnits (current spendable balance)\n- totalEarnedUnits (lifetime points - NOT 'earnedUnits'!)\n- totalSpending (lifetime spend amount)\n- monthsSinceJoiningProgram (tenure in months)\n- cumulatedEarnedUnits (similar to totalEarnedUnits)\n\nCOMMON MISTAKE: Using 'earnedUnits' will fail - use 'totalEarnedUnits' for lifetime points.\n\n### 2. Register and Reward Member:\nmember_create \u2192 points_add (welcome bonus) \u2192 member_get (verify)\n\n### 3. Record Purchase and Earn Points:\ntransaction_create (with customerData) \u2192 triggers campaigns \u2192 points auto-added\n\n### 4. Redeem Reward:\nreward_list \u2192 reward_buy (deducts points) \u2192 reward_redeem (mark coupon used)\n\n### 5. Assign Unmatched Transaction:\ntransaction_list (matched=false) \u2192 transaction_assign_member \u2192 points earned\n\n### 6. Check Member Tier Progress:\nmember_get_tier_progress \u2192 shows current tier, next tier, progress %\n\n### 7. Double Points for VIP Members:\nsegment_create (with transaction_count criteria) \u2192 campaign_create (targeting that segment with give_points effect and pointsRule: \"transaction.grossValue * 2\")\n\n### 8. Purchase Achievement with Badge:\nbadge_list (find or note badgeTypeId) \u2192 achievement_create (type+trigger+aggregation+period required, badgeTypeId)\n\n### 9. Create Targeted Promotion:\nsegment_create (define audience) \u2192 campaign_create (type: earning, target: segment, segmentIds: [segmentId])\n\n### 10. Track Member Gamification:\nachievement_list_member_achievements \u2192 badge_get_member_badges \u2192 achievement_get_member_progress\n\n## Discovery Paths:\n- Members: member_list \u2192 member_get \u2192 points_get_balance\n- Tiers: tierset_list \u2192 tierset_get \u2192 tierset_get_tiers\n- Rewards: reward_category_list \u2192 reward_list \u2192 reward_get\n- Transactions: transaction_list \u2192 transaction_get\n- Campaigns: campaign_list \u2192 campaign_get \u2192 campaign_simulate\n- Segments: segment_list \u2192 segment_get \u2192 segment_get_members \u2192 campaign_create (audience targeting)\n- Achievements: achievement_list \u2192 badge_list \u2192 achievement_create (with badge)\n- Member Gamification: achievement_list_member_achievements \u2192 badge_get_member_badges\n\n## Important Patterns:\n- TIER SETUP: conditionId REQUIRED for tier thresholds\n  1. tierset_create returns conditions but you need the id from tierset_get\n  2. The conditionId is in tierset_get response: conditions[].id (this IS the conditionId)\n  3. Use this conditionId in tierset_update_tiers for each tier's threshold\n- TIER ATTRIBUTES: Use 'totalEarnedUnits' (NOT 'earnedUnits') for lifetime points\n- walletType uses CODE (e.g., 'default'), not UUID\n- Points operations: check balance with points_get_balance before spending\n- Reward flow: reward_buy returns couponCode, use reward_redeem to mark used\n- Transactions auto-match to members via customerData (email, phone, loyaltyCardNumber)\n\n### Pagination:\n- Traditional pagination: use page + perPage params\n- Cursor pagination: provide cursor from previous response for efficient deep pagination\n- Cursor-enabled tools: member_list, transaction_list, points_get_history\n- First scroll request: cursor=\"\" (empty string)\n- Subsequent requests: use cursor value from previous response\n- When cursor provided, page param is ignored\n\n### Campaign Patterns:\n- Campaign types: direct (standard), referral (referral programs)\n- Triggers: transaction (purchase), custom_event, time, achievement, etc.\n- Effects: give_points, give_reward, deduct_unit\n- Target campaigns to segments or tiers using audience.target: \"segment\" and audience.segments array\n- campaign_create requires activity.startsAt, rules[].name, and effects[].effect (use key effect, not type). pointsRule is a STRING expression.\n\n### Points Expression (pointsRule):\npointsRule is a STRING expression, not an object. Examples:\n- Fixed: \"100\"\n- Per dollar: \"transaction.grossValue * 10\"\n- Category-based: \"transaction.category('electronics').grossValue * 5\"\n- Capped: \"(transaction.grossValue * 2 >= 100) ? 100 : transaction.grossValue * 2\"\n- Rounded: \"round_up(0.1 * transaction.grossValue)\"\n\n### Segment Patterns:\n- Parts use OR logic (member matches ANY part)\n- Criteria within a part use AND logic (member must match ALL criteria in that part)\n- Common criteria: transaction_count (working; requires min+max). Other criteria may be rejected by the API.\n\n### Achievement Patterns:\n- Triggers: transaction, custom_event, points_transfer, reward_redemption, referral, achievement, tier_change, profile_update\n- periodGoal sets the target (e.g., 5 purchases, 1000 points spent)\n- period.type defines timeframe: day, week, month, year, last_day, calendarDays, calendarWeeks, calendarMonths, calendarYears\n- aggregation.type defines counting method: quantity (count events only)\n- Link to badge via badgeTypeId - badge auto-created if doesn't exist\n- uniqueAttribute for counting distinct values (e.g., unique products)\n\n### Achievement Period Types:\n- \"day\": Count all-time when consecutive=1\n- \"week\": Count per week (use consecutive=1 for all-time weekly tracking)\n- \"month\": Count per month\n- \"year\": Count per year\n- \"last_day\": Rolling window of N days (e.g., value: 7 for last 7 days)\n- \"calendarDays\": Reset daily at midnight\n- \"calendarWeeks\": Reset weekly (Monday)\n- \"calendarMonths\": Reset monthly (1st of month)\n- \"calendarYears\": Reset yearly (January 1st)\n\n### Streak Achievement Example (7-day login streak):\n{\n  \"rules\": [{\n    \"trigger\": \"custom_event\",\n    \"event\": \"app_login\",\n    \"type\": \"direct\",\n    \"aggregation\": {\"type\": \"quantity\"},\n    \"completeRule\": {\n      \"periodGoal\": 1,\n      \"period\": {\"type\": \"last_day\", \"value\": 7, \"consecutive\": 1}\n    },\n    \"limit\": {\n      \"interval\": {\"type\": \"calendarDays\", \"value\": 1},\n      \"value\": 1\n    }\n  }]\n}\n\n### Custom Event Workflows:\n\n#### Create Custom Event Campaign:\n1. custom_event_schema_list \u2192 Check if event type exists\n2. custom_event_schema_create (if needed) \u2192 Define event type and fields\n3. campaign_create with trigger: \"custom_event\", event: \"{event_type}\"\n4. Send events via custom_event_send to trigger campaign\n\n#### Create Achievement with Custom Event:\n1. custom_event_schema_create \u2192 Define event (e.g., \"location_visit\")\n2. achievement_create with:\n   - rules[].trigger: \"custom_event\"\n   - rules[].event: \"{event_type}\"\n   - rules[].type: \"direct\"\n   - rules[].aggregation.type: \"quantity\"\n   - rules[].completeRule.periodGoal: {count}\n   - rules[].completeRule.period: { type: \"day\", consecutive: 1 } (all-time)\n\n#### Create Campaign Triggered by Achievement:\n1. achievement_create \u2192 Get achievementId from response\n2. campaign_create with:\n   - trigger: \"achievement\"\n   - achievementId: \"{achievement_id}\"\n   - rules with effects (give_points, give_reward)\n\n### Condition Operators (for campaigns/achievements):\n- is_equal, is_not_equal\n- gte, gt, lte, lt\n- is_between, is_not_between\n- is_time_between\n- is_day_of_week, is_day_of_month\n- contains, not_contains\n- starts_with, ends_with\n- one_of, not_one_of\n- expression (for custom logic)\n\n## Common Campaign Patterns (Industry-Agnostic)\n\nThese patterns work for any loyalty program - retail, QSR, aviation, fan engagement, hospitality, etc.\n\n### Pattern 1: Count Events Toward Goal (Achievements)\nUse case: Track member actions (visits, purchases, logins, check-ins) toward a milestone.\n1. custom_event_schema_create \u2192 Define your action type (e.g., \"store_visit\", \"app_login\")\n2. achievement_create with:\n   - trigger: \"custom_event\"\n   - event: \"{your_event_code}\"\n   - aggregation: { type: \"quantity\" }\n   - completeRule: { periodGoal: {count}, period: { type: \"day\", consecutive: 1 } }\n3. custom_event_send to log each action\n\n### Pattern 2: Points Per Action (Instant Rewards)\nUse case: Award instant points for each qualifying action.\n1. custom_event_schema_create (if not using transaction)\n2. campaign_create with:\n   - trigger: \"custom_event\" (or \"transaction\")\n   - event: \"{event_code}\" (for custom events)\n   - rules: [{ effects: [{ effect: \"give_points\", pointsRule: \"50\" }] }]\n\n### Pattern 3: Conditional Rewards (Bonus Conditions)\nUse case: Award points only when a condition is met (e.g., early arrival, large purchase).\nUse ternary expressions in pointsRule instead of conditions array:\n- pointsRule: \"event.body.minutes_before >= 60 ? 25 : 0\"\n- pointsRule: \"transaction.grossValue >= 100 ? 50 : 0\"\n\n### Pattern 4: Execution Limits (Anti-Fraud)\nUse case: Limit rewards to prevent abuse (once per day, once per week).\nCampaign limits structure:\n{\n  \"limits\": {\n    \"executionsPerMember\": {\n      \"value\": 1,\n      \"interval\": { \"type\": \"calendarDays\", \"value\": 1 }\n    }\n  }\n}\nNote: Use \"calendarDays\" (not \"days\"), \"calendarWeeks\", \"calendarMonths\", \"calendarYears\".\nOmit interval entirely for lifetime/forever limit.\n\n### Pattern 5: Achievement-Triggered Bonus\nUse case: Award bonus points/rewards when member completes an achievement.\n1. achievement_create \u2192 Get achievementId from response\n2. campaign_create with:\n   - trigger: \"achievement\"\n   - achievementId: \"{achievement_id}\"\n   - rules with give_points or give_reward effect\n\n### Pattern 6: Tiered Milestones\nUse case: Multiple achievement levels (bronze/silver/gold, 5/10/25 visits).\nCreate multiple achievements with increasing periodGoal values,\neach linked to a different bonus campaign with increasing rewards.\n\n### Pattern 7: Time-Limited Promotion\nUse case: Seasonal or promotional campaigns.\n{\n  \"activity\": {\n    \"startsAt\": \"2026-01-01 00:00+00:00\",\n    \"endsAt\": \"2026-03-31 23:59+00:00\"\n  }\n}\n\n### Pattern 8: Streak Tracking\nUse case: Reward consecutive daily/weekly actions (login streaks, workout streaks).\nAchievement with:\n- completeRule.period: { type: \"last_day\", value: 7 } (rolling 7-day window)\n- limit: { value: 1, interval: { type: \"calendarDays\", value: 1 } } (max 1 per day)\n\n## Phase 3: Analytics, Admin, Roles & Stores\n\n### Domain Model (Extended)\n\nAdmin (system user)\n  \u2514\u2500\u2500 Roles (permission sets)\n      \u2514\u2500\u2500 Permissions (resource + access level)\n  \u2514\u2500\u2500 API Keys (programmatic access)\n\nStore (multi-tenant container)\n  \u2514\u2500\u2500 Members, Campaigns, Rewards (isolated per store)\n\nAudit Log (compliance tracking)\n  \u2514\u2500\u2500 eventType, entityType, entityId, username, timestamp\n\n### Analytics Workflows:\n\n#### 11. Get Program Overview:\nanalytics_dashboard \u2192 analytics_tiers \u2192 analytics_members\n\n#### 12. Analyze Points Economy:\nanalytics_points \u2192 analytics_units (per wallet) \u2192 points_get_histogram\n\n#### 13. Measure Campaign Performance:\nanalytics_campaigns \u2192 analytics_campaign_detail (specific campaign)\n\n#### 14. Track Transactions:\nanalytics_transactions \u2192 transaction_list (details)\n\n### Aggregation Queries (Top Spenders, Purchase Analysis):\n\nIMPORTANT: For queries like \"top 5 spenders in July 2025\", use this approach:\n\n#### 15. Find Top Spenders by Date Range:\n1. transaction_list(purchasedAtFrom, purchasedAtTo, perPage=50, cursor='') - returns customerId with each transaction\n2. Use cursor pagination to fetch ALL pages - even if there are 1000+ transactions\n3. Aggregate grossValue by customerId in your code\n4. Sort by total spent, take top N\n5. member_get for each top spender to get names/details\n\nCRITICAL - DO NOT TRY TO BE SMART OR OPTIMIZE:\n- ALWAYS iterate through ALL pages using cursor pagination - this is the ONLY correct approach\n- DO NOT skip pages or try to sample data - you will get inaccurate results\n- DO NOT use transaction_get individually - transaction_list already includes customerId\n- DO NOT try to find \"smarter\" analytics endpoints - they don't exist for per-customer aggregation\n- Large datasets (1000+ transactions) are normal - just keep paginating until cursor is empty\n- Start with cursor='' (empty string), use returned cursor for next request, repeat until done\n\nExample: Top 5 spenders July 2025\n- First request: transaction_list(purchasedAtFrom: \"2025-07-01\", purchasedAtTo: \"2025-07-31\", perPage: 50, cursor: \"\")\n- Each result includes: transactionId, grossValue, customerId, purchasedAt\n- Keep fetching with returned cursor until response has no cursor or empty transactions\n- Even if there are 1500 transactions (30 pages), iterate through ALL of them\n- Group by customerId, sum grossValue, sort descending, take 5\n\n### Admin & Security Workflows:\n\n#### 15. Create Admin with Limited Role:\nacl_get_resources \u2192 role_create \u2192 admin_create (with roleId)\n\n#### 16. Generate API Key for Integration:\nadmin_get \u2192 apikey_create \u2192 SAVE TOKEN IMMEDIATELY (shown once!)\n\n#### 17. Audit User Actions:\naudit_list (filter by username/entity) \u2192 audit_export (compliance report)\n\n### Store Multi-Tenancy:\n\n#### 18. Create New Store:\nstore_create \u2192 configure campaigns/tiers \u2192 member_create (with storeCode)\n\n### Analytics Query Patterns:\n- All analytics tools support dateFrom/dateTo ISO date filters\n- analytics_dashboard: high-level program metrics\n- analytics_units: wallet-specific metrics (requires walletTypeCode)\n- analytics_campaign_detail: detailed metrics for single campaign\n\n### Admin \u2192 Role \u2192 Permission Model:\n\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510     \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2510     \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502  Admin  \u2502\u2500\u2500\u2500\u2500\u25B6\u2502 Role \u2502\u2500\u2500\u2500\u2500\u25B6\u2502 Permission \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518     \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2518     \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n     \u2502                            \u2502\n     \u2502                       resource + access\n     \u2502                       (VIEW, MODIFY, etc.)\n     \u25BC\n\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 API Key \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\n### Store Multi-Tenancy:\n- Each store is isolated: members, campaigns, rewards, transactions\n- storeCode parameter routes requests to correct tenant\n- Default store used when storeCode omitted\n- IMPORTANT: Do NOT pass storeCode parameter unless the user explicitly asks to work with a different store. The configured default store should always be used unless the user requests otherwise.\n\n## Phase 4: Webhooks, Import & Export\n\n### Domain Model (Extended)\n\nWebhook Subscription (event notification)\n  \u2514\u2500\u2500 eventName (event to subscribe to)\n  \u2514\u2500\u2500 url (callback endpoint)\n  \u2514\u2500\u2500 headers (custom HTTP headers)\n\nImport (bulk data upload)\n  \u2514\u2500\u2500 type: member, groupValue, segmentMembers, unitTransferAdding, etc.\n  \u2514\u2500\u2500 status: pending, processing, succeed, failed\n  \u2514\u2500\u2500 items (individual row results)\n\nExport (bulk data download)\n  \u2514\u2500\u2500 type: campaignCode, member, memberTier, memberSegment, rewardFulfillment\n  \u2514\u2500\u2500 status: pending, done, failed, error\n  \u2514\u2500\u2500 CSV file (when status='done')\n\n### Webhook Workflows:\n\n#### 19. Subscribe to Member Events for CRM Sync:\nwebhook_events \u2192 webhook_create (eventName: 'member.created', url: 'https://crm.example.com/webhook')\n\n#### 20. List and Manage Subscriptions:\nwebhook_list \u2192 webhook_get \u2192 webhook_update or webhook_delete\n\n### Import Workflows:\n\n#### 21. Bulk Import Members from CSV:\nimport_create (type: 'member', fileContent: CSV data) \u2192 import_list \u2192 import_get (check status)\n\n#### 22. Bulk Add Points to Members:\nimport_create (type: 'unitTransferAdding', fileContent: CSV) \u2192 poll import_get until complete\n\n### Export Workflows:\n\n#### 23. Export Campaign Codes:\nexport_create (type: 'campaignCode', filters: { campaignId }) \u2192 poll export_get (until status='done') \u2192 export_download\n\n#### 24. Export Member Data:\nexport_create (type: 'member') \u2192 export_get \u2192 export_download (returns CSV)\n\n### Webhook Patterns:\n- Use webhook_events to discover available event types before subscribing\n- API uses wrapper: { webhookSubscription: { eventName, url, headers? } }\n- Common events: member.created, member.updated, transaction.created, reward.purchased\n\n### Import Patterns:\n- Import is async: create returns importId, poll status with import_get\n- CSV format required - provide plain text, not base64\n- Types: member, groupValue, segmentMembers, unitTransferAdding, unitTransferSpending, transaction, campaignCode, rewardCoupon\n\n### Export Patterns:\n- Export is async: create returns exportId, poll status until 'done'\n- API body wrapper varies by type: { campaignCode: { filters... } }\n- Only call export_download when status='done'\n- Types: campaignCode, member, memberTier, memberSegment, rewardFulfillment\n";
+export declare const SERVER_INSTRUCTIONS = "\nOpen Loyalty MCP Server - Complete Loyalty Program Management\n\n## Domain Model\n\nMember (loyalty program participant)\n  \u2514\u2500\u2500 Points (wallet balance, transfers)\n  \u2514\u2500\u2500 Tier (current level: Bronze, Silver, Gold)\n  \u2514\u2500\u2500 Transactions (purchase history)\n  \u2514\u2500\u2500 Rewards (redeemed coupons)\n  \u2514\u2500\u2500 Achievements (gamification progress)\n  \u2514\u2500\u2500 Badges (visual rewards from achievements)\n\nTierSet (loyalty program structure)\n  \u2514\u2500\u2500 Conditions (criteria: activeUnits, totalSpending)\n  \u2514\u2500\u2500 Tiers (levels with thresholds)\n\nWalletType (points currency configuration)\n\nReward (redeemable items)\n  \u2514\u2500\u2500 Categories (reward groupings)\n\nCampaign (automated points/rewards rules)\n  \u2514\u2500\u2500 Type (earning, spending, custom, instant_reward)\n  \u2514\u2500\u2500 Trigger (transaction, custom_event, points_transfer)\n  \u2514\u2500\u2500 Rules (SKU, category, transaction amount conditions)\n  \u2514\u2500\u2500 Effects (give_points, multiply_points, percentage_discount)\n  \u2514\u2500\u2500 Targeting (segments, tiers for audience)\n\nSegment (member audience grouping)\n  \u2514\u2500\u2500 Parts (groups of criteria - OR logic between parts)\n      \u2514\u2500\u2500 Criteria (conditions - AND logic within part)\n          Types: transaction_count (working; requires min+max). Other types may be rejected by the API.\n\nAchievement (gamification goals)\n  \u2514\u2500\u2500 Trigger (transaction, custom_event, points_transfer, reward_redemption, referral, achievement, tier_change, profile_update)\n  \u2514\u2500\u2500 CompleteRule (periodGoal, period type, unique counting)\n  \u2514\u2500\u2500 Badge (visual reward when completed)\n\nBadge (visual recognition)\n  \u2514\u2500\u2500 Linked to achievements via badgeTypeId\n  \u2514\u2500\u2500 Auto-created when referenced by achievement\n\n## Key Workflows\n\n### 1. Create Multi-tier Loyalty Program:\nCRITICAL CONCEPT: A tier set is a CONTAINER that holds ALL tiers (Bronze/Silver/Gold/etc).\n- Create exactly ONE tier set\n- Add ALL tiers to it in ONE call to tierset_update_tiers\n- DO NOT create multiple tier sets for different tiers!\n\nRECOMMENDED WORKFLOW:\n1. wallet_type_list \u2192 Get wallet code (usually \"default\")\n2. tierset_list \u2192 Check if tier set already exists\n3. IF EXISTS: tierset_get \u2192 Get conditionId from existing tier set\n   ELSE: tierset_create \u2192 Create ONE tier set, then tierset_get to get conditionId\n4. tierset_update_tiers \u2192 Define ALL tier thresholds in ONE call:\n   tiers: [\n     { name: \"Bronze\", conditions: [{ conditionId: \"xxx\", value: 0 }] },\n     { name: \"Silver\", conditions: [{ conditionId: \"xxx\", value: 500 }] },\n     { name: \"Gold\", conditions: [{ conditionId: \"xxx\", value: 1000 }] },\n     { name: \"Platinum\", conditions: [{ conditionId: \"xxx\", value: 2000 }] }\n   ]\n5. tierset_get_tiers \u2192 Verify tiers created correctly\n\nGOTCHA - Valid tier condition attributes:\n- activeUnits (current spendable balance)\n- totalEarnedUnits (lifetime points - NOT 'earnedUnits'!)\n- totalSpending (lifetime spend amount)\n- monthsSinceJoiningProgram (tenure in months)\n\nCOMMON MISTAKE: Using 'earnedUnits' will fail - use 'totalEarnedUnits' for lifetime points.\n\n### 2. Register and Reward Member:\nmember_create \u2192 points_add (welcome bonus) \u2192 member_get (verify)\n\n### 3. Record Purchase and Earn Points:\ntransaction_create (with customerData) \u2192 triggers campaigns \u2192 points auto-added\n\n### 4. Redeem Reward:\nreward_list \u2192 reward_buy (deducts points) \u2192 reward_redeem (mark coupon used)\n\n### 5. Assign Unmatched Transaction:\ntransaction_list (matched=false) \u2192 transaction_assign_member \u2192 points earned\n\n### 6. Check Member Tier Progress:\nmember_get_tier_progress \u2192 shows current tier, next tier, progress %\n\n### 7. Double Points for VIP Members:\nsegment_create (with transaction_count criteria) \u2192 campaign_create (targeting that segment with give_points effect and pointsRule: \"transaction.grossValue * 2\")\n\n### 8. Purchase Achievement with Badge:\nbadge_list (find or note badgeTypeId) \u2192 achievement_create (type+trigger+aggregation+period required, badgeTypeId)\n\n### 9. Create Targeted Promotion:\nsegment_create (define audience) \u2192 campaign_create (type: earning, target: segment, segmentIds: [segmentId])\n\n### 10. Track Member Gamification:\nachievement_list_member_achievements \u2192 badge_get_member_badges \u2192 achievement_get_member_progress\n\n## Discovery Paths:\n- Members: member_list \u2192 member_get \u2192 points_get_balance\n- Tiers: tierset_list \u2192 tierset_get \u2192 tierset_get_tiers\n- Rewards: reward_category_list \u2192 reward_list \u2192 reward_get\n- Transactions: transaction_list \u2192 transaction_get\n- Campaigns: campaign_list \u2192 campaign_get \u2192 campaign_simulate\n- Segments: segment_list \u2192 segment_get \u2192 segment_get_members \u2192 campaign_create (audience targeting)\n- Achievements: achievement_list \u2192 badge_list \u2192 achievement_create (with badge)\n- Member Gamification: achievement_list_member_achievements \u2192 badge_get_member_badges\n\n## Important Patterns:\n- TIER SET = CONTAINER: One tier set holds ALL tiers (Bronze/Silver/Gold/etc)\n  - Create ONE tier set, add ALL tiers in ONE tierset_update_tiers call\n  - DO NOT create multiple tier sets for different tiers!\n- TIER SETUP: conditionId REQUIRED for tier thresholds\n  1. tierset_create returns conditions but you need the id from tierset_get\n  2. The conditionId is in tierset_get response: conditions[].id (this IS the conditionId)\n  3. Use the SAME conditionId for ALL tiers in tierset_update_tiers\n- TIER ATTRIBUTES: Use 'totalEarnedUnits' (NOT 'earnedUnits') for lifetime points\n- walletType uses CODE (e.g., 'default'), not UUID\n- Points operations: check balance with points_get_balance before spending\n- Reward flow: reward_buy returns couponCode, use reward_redeem to mark used\n- Transactions auto-match to members via customerData (email, phone, loyaltyCardNumber)\n\n### Pagination:\n- Traditional pagination: use page + perPage params\n- Cursor pagination: provide cursor from previous response for efficient deep pagination\n- Cursor-enabled tools: member_list, transaction_list, points_get_history\n- First scroll request: cursor=\"\" (empty string)\n- Subsequent requests: use cursor value from previous response\n- When cursor provided, page param is ignored\n\n### Campaign Patterns:\n- Campaign types: direct (standard), referral (referral programs)\n- Triggers: transaction (purchase), custom_event, time, achievement, etc.\n- Effects: give_points, give_reward, deduct_unit\n- Target campaigns to segments or tiers using audience.target: \"segment\" and audience.segments array\n- campaign_create requires activity.startsAt, rules[].name, and effects[].effect (use key effect, not type). pointsRule is a STRING expression.\n\n### Points Expression (pointsRule):\npointsRule is a STRING expression, not an object. Examples:\n- Fixed: \"100\"\n- Per dollar: \"transaction.grossValue * 10\"\n- Category-based: \"transaction.category('electronics').grossValue * 5\"\n- Capped: \"(transaction.grossValue * 2 >= 100) ? 100 : transaction.grossValue * 2\"\n- Rounded: \"round_up(0.1 * transaction.grossValue)\"\n\n### Segment Patterns:\n- Parts use OR logic (member matches ANY part)\n- Criteria within a part use AND logic (member must match ALL criteria in that part)\n- Common criteria: transaction_count (working; requires min+max). Other criteria may be rejected by the API.\n\n### Achievement Patterns:\n- Triggers: transaction, custom_event, points_transfer, reward_redemption, referral, achievement, tier_change, profile_update\n- periodGoal sets the target (e.g., 5 purchases, 1000 points spent)\n- period.type defines timeframe: day, week, month, year, last_day, calendarDays, calendarWeeks, calendarMonths, calendarYears\n- aggregation.type defines counting method: quantity (count events only)\n- Link to badge via badgeTypeId - badge auto-created if doesn't exist\n- uniqueAttribute for counting distinct values (e.g., unique products)\n\n### Achievement Period Types:\n- \"day\": Count all-time when consecutive=1\n- \"week\": Count per week (use consecutive=1 for all-time weekly tracking)\n- \"month\": Count per month\n- \"year\": Count per year\n- \"last_day\": Rolling window of N days (e.g., value: 7 for last 7 days)\n- \"calendarDays\": Reset daily at midnight\n- \"calendarWeeks\": Reset weekly (Monday)\n- \"calendarMonths\": Reset monthly (1st of month)\n- \"calendarYears\": Reset yearly (January 1st)\n\n### Streak Achievement Example (7-day login streak):\n{\n  \"rules\": [{\n    \"trigger\": \"custom_event\",\n    \"event\": \"app_login\",\n    \"type\": \"direct\",\n    \"aggregation\": {\"type\": \"quantity\"},\n    \"completeRule\": {\n      \"periodGoal\": 1,\n      \"period\": {\"type\": \"last_day\", \"value\": 7, \"consecutive\": 1}\n    },\n    \"limit\": {\n      \"interval\": {\"type\": \"calendarDays\", \"value\": 1},\n      \"value\": 1\n    }\n  }]\n}\n\n### Custom Event Workflows:\n\n#### Create Custom Event Campaign:\n1. custom_event_schema_list \u2192 Check if event type exists\n2. custom_event_schema_create (if needed) \u2192 Define event type and fields\n3. campaign_create with trigger: \"custom_event\", event: \"{event_type}\"\n4. Send events via custom_event_send to trigger campaign\n\n#### Create Achievement with Custom Event:\n1. custom_event_schema_create \u2192 Define event (e.g., \"location_visit\")\n2. achievement_create with:\n   - rules[].trigger: \"custom_event\"\n   - rules[].event: \"{event_type}\"\n   - rules[].type: \"direct\"\n   - rules[].aggregation.type: \"quantity\"\n   - rules[].completeRule.periodGoal: {count}\n   - rules[].completeRule.period: { type: \"day\", consecutive: 1 } (all-time)\n\n#### Create Campaign Triggered by Achievement:\n1. achievement_create \u2192 Get achievementId from response\n2. campaign_create with:\n   - trigger: \"achievement\"\n   - achievementId: \"{achievement_id}\"\n   - rules with effects (give_points, give_reward)\n\n### Condition Operators (for campaigns/achievements):\n- is_equal, is_not_equal\n- gte, gt, lte, lt\n- is_between, is_not_between\n- is_time_between\n- is_day_of_week, is_day_of_month\n- contains, not_contains\n- starts_with, ends_with\n- one_of, not_one_of\n- expression (for custom logic)\n\n## Common Campaign Patterns (Industry-Agnostic)\n\nThese patterns work for any loyalty program - retail, QSR, aviation, fan engagement, hospitality, etc.\n\n### Pattern 1: Count Events Toward Goal (Achievements)\nUse case: Track member actions (visits, purchases, logins, check-ins) toward a milestone.\n1. custom_event_schema_create \u2192 Define your action type (e.g., \"store_visit\", \"app_login\")\n2. achievement_create with:\n   - trigger: \"custom_event\"\n   - event: \"{your_event_code}\"\n   - aggregation: { type: \"quantity\" }\n   - completeRule: { periodGoal: {count}, period: { type: \"day\", consecutive: 1 } }\n3. custom_event_send to log each action\n\n### Pattern 2: Points Per Action (Instant Rewards)\nUse case: Award instant points for each qualifying action.\n1. custom_event_schema_create (if not using transaction)\n2. campaign_create with:\n   - trigger: \"custom_event\" (or \"transaction\")\n   - event: \"{event_code}\" (for custom events)\n   - rules: [{ effects: [{ effect: \"give_points\", pointsRule: \"50\" }] }]\n\n### Pattern 3: Conditional Rewards (Bonus Conditions)\nUse case: Award points only when a condition is met (e.g., early arrival, large purchase).\nUse ternary expressions in pointsRule instead of conditions array:\n- pointsRule: \"event.body.minutes_before >= 60 ? 25 : 0\"\n- pointsRule: \"transaction.grossValue >= 100 ? 50 : 0\"\n\n### Pattern 4: Execution Limits (Anti-Fraud)\nUse case: Limit rewards to prevent abuse (once per day, once per week).\nCampaign limits structure:\n{\n  \"limits\": {\n    \"executionsPerMember\": {\n      \"value\": 1,\n      \"interval\": { \"type\": \"calendarDays\", \"value\": 1 }\n    }\n  }\n}\nNote: Use \"calendarDays\" (not \"days\"), \"calendarWeeks\", \"calendarMonths\", \"calendarYears\".\nOmit interval entirely for lifetime/forever limit.\n\n### Pattern 5: Achievement-Triggered Bonus\nUse case: Award bonus points/rewards when member completes an achievement.\n1. achievement_create \u2192 Get achievementId from response\n2. campaign_create with:\n   - trigger: \"achievement\"\n   - achievementId: \"{achievement_id}\"\n   - rules with give_points or give_reward effect\n\n### Pattern 6: Tiered Milestones\nUse case: Multiple achievement levels (bronze/silver/gold, 5/10/25 visits).\nCreate multiple achievements with increasing periodGoal values,\neach linked to a different bonus campaign with increasing rewards.\n\n### Pattern 7: Time-Limited Promotion\nUse case: Seasonal or promotional campaigns.\n{\n  \"activity\": {\n    \"startsAt\": \"2026-01-01 00:00+00:00\",\n    \"endsAt\": \"2026-03-31 23:59+00:00\"\n  }\n}\n\n### Pattern 8: Streak Tracking\nUse case: Reward consecutive daily/weekly actions (login streaks, workout streaks).\nAchievement with:\n- completeRule.period: { type: \"last_day\", value: 7 } (rolling 7-day window)\n- limit: { value: 1, interval: { type: \"calendarDays\", value: 1 } } (max 1 per day)\n\n## Phase 3: Analytics, Admin, Roles & Stores\n\n### Domain Model (Extended)\n\nAdmin (system user)\n  \u2514\u2500\u2500 Roles (permission sets)\n      \u2514\u2500\u2500 Permissions (resource + access level)\n  \u2514\u2500\u2500 API Keys (programmatic access)\n\nStore (multi-tenant container)\n  \u2514\u2500\u2500 Members, Campaigns, Rewards (isolated per store)\n\nAudit Log (compliance tracking)\n  \u2514\u2500\u2500 eventType, entityType, entityId, username, timestamp\n\n### Analytics Workflows:\n\n#### 11. Get Program Overview:\nanalytics_dashboard \u2192 analytics_tiers \u2192 analytics_members\n\n#### 12. Analyze Points Economy:\nanalytics_points \u2192 analytics_units (per wallet) \u2192 points_get_histogram\n\n#### 13. Measure Campaign Performance:\nanalytics_campaigns \u2192 analytics_campaign_detail (specific campaign)\n\n#### 14. Track Transactions:\nanalytics_transactions \u2192 transaction_list (details)\n\n### Aggregation Queries (Top Spenders, Purchase Analysis):\n\nIMPORTANT: For queries like \"top 5 spenders in July 2025\", use this approach:\n\n#### 15. Find Top Spenders by Date Range:\n1. transaction_list(purchasedAtFrom, purchasedAtTo, perPage=50, cursor='') - returns customerId with each transaction\n2. Use cursor pagination to fetch ALL pages - even if there are 1000+ transactions\n3. Aggregate grossValue by customerId in your code\n4. Sort by total spent, take top N\n5. member_get for each top spender to get names/details\n\nCRITICAL - DO NOT TRY TO BE SMART OR OPTIMIZE:\n- ALWAYS iterate through ALL pages using cursor pagination - this is the ONLY correct approach\n- DO NOT skip pages or try to sample data - you will get inaccurate results\n- DO NOT use transaction_get individually - transaction_list already includes customerId\n- DO NOT try to find \"smarter\" analytics endpoints - they don't exist for per-customer aggregation\n- Large datasets (1000+ transactions) are normal - just keep paginating until cursor is empty\n- Start with cursor='' (empty string), use returned cursor for next request, repeat until done\n\nExample: Top 5 spenders July 2025\n- First request: transaction_list(purchasedAtFrom: \"2025-07-01\", purchasedAtTo: \"2025-07-31\", perPage: 50, cursor: \"\")\n- Each result includes: transactionId, grossValue, customerId, purchasedAt\n- Keep fetching with returned cursor until response has no cursor or empty transactions\n- Even if there are 1500 transactions (30 pages), iterate through ALL of them\n- Group by customerId, sum grossValue, sort descending, take 5\n\n### Admin & Security Workflows:\n\n#### 15. Create Admin with Limited Role:\nacl_get_resources \u2192 role_create \u2192 admin_create (with roleId)\n\n#### 16. Generate API Key for Integration:\nadmin_get \u2192 apikey_create \u2192 SAVE TOKEN IMMEDIATELY (shown once!)\n\n#### 17. Audit User Actions:\naudit_list (filter by username/entity) \u2192 audit_export (compliance report)\n\n### Store Multi-Tenancy:\n\n#### 18. Create New Store:\nstore_create \u2192 configure campaigns/tiers \u2192 member_create (with storeCode)\n\n### Analytics Query Patterns:\n- All analytics tools support dateFrom/dateTo ISO date filters\n- analytics_dashboard: high-level program metrics\n- analytics_units: wallet-specific metrics (requires walletTypeCode)\n- analytics_campaign_detail: detailed metrics for single campaign\n\n### Admin \u2192 Role \u2192 Permission Model:\n\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510     \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2510     \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502  Admin  \u2502\u2500\u2500\u2500\u2500\u25B6\u2502 Role \u2502\u2500\u2500\u2500\u2500\u25B6\u2502 Permission \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518     \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2518     \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n     \u2502                            \u2502\n     \u2502                       resource + access\n     \u2502                       (VIEW, MODIFY, etc.)\n     \u25BC\n\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 API Key \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\n### Store Multi-Tenancy:\n- Each store is isolated: members, campaigns, rewards, transactions\n- storeCode parameter routes requests to correct tenant\n- Default store used when storeCode omitted\n- IMPORTANT: Do NOT pass storeCode parameter unless the user explicitly asks to work with a different store. The configured default store should always be used unless the user requests otherwise.\n\n## Phase 4: Webhooks, Import & Export\n\n### Domain Model (Extended)\n\nWebhook Subscription (event notification)\n  \u2514\u2500\u2500 eventName (event to subscribe to)\n  \u2514\u2500\u2500 url (callback endpoint)\n  \u2514\u2500\u2500 headers (custom HTTP headers)\n\nImport (bulk data upload)\n  \u2514\u2500\u2500 type: member, groupValue, segmentMembers, unitTransferAdding, etc.\n  \u2514\u2500\u2500 status: pending, processing, succeed, failed\n  \u2514\u2500\u2500 items (individual row results)\n\nExport (bulk data download)\n  \u2514\u2500\u2500 type: campaignCode, member, memberTier, memberSegment, rewardFulfillment\n  \u2514\u2500\u2500 status: pending, done, failed, error\n  \u2514\u2500\u2500 CSV file (when status='done')\n\n### Webhook Workflows:\n\n#### 19. Subscribe to Member Events for CRM Sync:\nwebhook_events \u2192 webhook_create (eventName: 'member.created', url: 'https://crm.example.com/webhook')\n\n#### 20. List and Manage Subscriptions:\nwebhook_list \u2192 webhook_get \u2192 webhook_update or webhook_delete\n\n### Import Workflows:\n\n#### 21. Bulk Import Members from CSV:\nimport_create (type: 'member', fileContent: CSV data) \u2192 import_list \u2192 import_get (check status)\n\n#### 22. Bulk Add Points to Members:\nimport_create (type: 'unitTransferAdding', fileContent: CSV) \u2192 poll import_get until complete\n\n### Export Workflows:\n\n#### 23. Export Campaign Codes:\nexport_create (type: 'campaignCode', filters: { campaignId }) \u2192 poll export_get (until status='done') \u2192 export_download\n\n#### 24. Export Member Data:\nexport_create (type: 'member') \u2192 export_get \u2192 export_download (returns CSV)\n\n### Webhook Patterns:\n- Use webhook_events to discover available event types before subscribing\n- API uses wrapper: { webhookSubscription: { eventName, url, headers? } }\n- Common events: member.created, member.updated, transaction.created, reward.purchased\n\n### Import Patterns:\n- Import is async: create returns importId, poll status with import_get\n- CSV format required - provide plain text, not base64\n- Types: member, groupValue, segmentMembers, unitTransferAdding, unitTransferSpending, transaction, campaignCode, rewardCoupon\n\n### Export Patterns:\n- Export is async: create returns exportId, poll status until 'done'\n- API body wrapper varies by type: { campaignCode: { filters... } }\n- Only call export_download when status='done'\n- Types: campaignCode, member, memberTier, memberSegment, rewardFulfillment\n";

package/dist/instructions.js

@@ -47,13 +47,24 @@ Badge (visual recognition)
 
 ## Key Workflows
 
-### 1. Create 3-tier Loyalty Program:
+### 1. Create Multi-tier Loyalty Program:
+CRITICAL CONCEPT: A tier set is a CONTAINER that holds ALL tiers (Bronze/Silver/Gold/etc).
+- Create exactly ONE tier set
+- Add ALL tiers to it in ONE call to tierset_update_tiers
+- DO NOT create multiple tier sets for different tiers!
+
 RECOMMENDED WORKFLOW:
 1. wallet_type_list → Get wallet code (usually "default")
 2. tierset_list → Check if tier set already exists
 3. IF EXISTS: tierset_get → Get conditionId from existing tier set
-   ELSE: tierset_create → Create new, then tierset_get to get conditionId
-4. tierset_update_tiers → Define tier thresholds using conditionId
+   ELSE: tierset_create → Create ONE tier set, then tierset_get to get conditionId
+4. tierset_update_tiers → Define ALL tier thresholds in ONE call:
+   tiers: [
+     { name: "Bronze", conditions: [{ conditionId: "xxx", value: 0 }] },
+     { name: "Silver", conditions: [{ conditionId: "xxx", value: 500 }] },
+     { name: "Gold", conditions: [{ conditionId: "xxx", value: 1000 }] },
+     { name: "Platinum", conditions: [{ conditionId: "xxx", value: 2000 }] }
+   ]
 5. tierset_get_tiers → Verify tiers created correctly
 
 GOTCHA - Valid tier condition attributes:
@@ -61,7 +72,6 @@ GOTCHA - Valid tier condition attributes:
 - totalEarnedUnits (lifetime points - NOT 'earnedUnits'!)
 - totalSpending (lifetime spend amount)
 - monthsSinceJoiningProgram (tenure in months)
-- cumulatedEarnedUnits (similar to totalEarnedUnits)
 
 COMMON MISTAKE: Using 'earnedUnits' will fail - use 'totalEarnedUnits' for lifetime points.
 
@@ -103,10 +113,13 @@ achievement_list_member_achievements → badge_get_member_badges → achievement
 - Member Gamification: achievement_list_member_achievements → badge_get_member_badges
 
 ## Important Patterns:
+- TIER SET = CONTAINER: One tier set holds ALL tiers (Bronze/Silver/Gold/etc)
+  - Create ONE tier set, add ALL tiers in ONE tierset_update_tiers call
+  - DO NOT create multiple tier sets for different tiers!
 - TIER SETUP: conditionId REQUIRED for tier thresholds
   1. tierset_create returns conditions but you need the id from tierset_get
   2. The conditionId is in tierset_get response: conditions[].id (this IS the conditionId)
-  3. Use this conditionId in tierset_update_tiers for each tier's threshold
+  3. Use the SAME conditionId for ALL tiers in tierset_update_tiers
 - TIER ATTRIBUTES: Use 'totalEarnedUnits' (NOT 'earnedUnits') for lifetime points
 - walletType uses CODE (e.g., 'default'), not UUID
 - Points operations: check balance with points_get_balance before spending

package/dist/tools/reward/handlers.d.ts

@@ -35,6 +35,8 @@ export declare function rewardCreate(input: {
         from: string;
         to: string;
     };
+    usageLimitPerUser?: number;
+    usageLimitGeneral?: number;
     costInPoints?: number;
     usageInstruction?: string;
     active?: boolean;

package/dist/tools/reward/handlers.js

@@ -46,16 +46,22 @@ export async function rewardList(input) {
 }
 export async function rewardCreate(input) {
     const storeCode = getStoreCode(input.storeCode);
-    // API requires: translations (name only), reward (type), activity, visibility
-    // NOTE: usageLimit is NOT supported at creation time - API rejects it as "extra fields"
-    // Use reward_update after creation to set usageLimit
+    // API requires: translations (name only), reward (type), activity, visibility, usageLimit
     // NOTE: description is NOT supported by the API at creation time
+    // CRITICAL: usageLimit shape depends on reward TYPE:
+    //   - material/fortune_wheel: require BOTH perUser AND general
+    //   - static_coupon/dynamic_coupon/conversion_coupon: require ONLY perUser (general is rejected as "extra fields")
+    const isCouponType = ["static_coupon", "dynamic_coupon", "conversion_coupon"].includes(input.reward);
+    const usageLimit = { perUser: input.usageLimitPerUser ?? 0 };
+    if (!isCouponType) {
+        usageLimit.general = input.usageLimitGeneral ?? 0;
+    }
     const payload = omitUndefined({
         translations: input.translations,
         reward: input.reward,
         activity: input.activity,
         visibility: input.visibility,
-        // usageLimit: NOT SUPPORTED at creation - use update after creation
+        usageLimit,
         costInPoints: input.costInPoints,
         usageInstruction: input.usageInstruction,
         active: input.active,
@@ -76,6 +82,20 @@ export async function rewardCreate(input) {
         };
     }
     catch (error) {
+        // Check for invalid reward type
+        const axiosError = error;
+        const apiErrors = axiosError.response?.data?.errors || [];
+        const rewardTypeError = apiErrors.find(e => e.path === "reward" && e.message.includes("selected choice is invalid"));
+        if (rewardTypeError) {
+            throw new OpenLoyaltyError({
+                code: "INVALID_REWARD_TYPE",
+                message: `Reward type '${input.reward}' is not valid`,
+                hint: "Valid reward types: 'material' (physical goods), 'static_coupon' (fixed discount code), " +
+                    "'dynamic_coupon' (variable value coupon), 'conversion_coupon' (points-to-coupon conversion), " +
+                    "'fortune_wheel' (gamified reward). NOTE: 'discount_code' is NOT a valid type - use 'static_coupon' instead.",
+                relatedTool: "ol_reward_create",
+            });
+        }
         throw formatApiError(error, "ol_reward_create");
     }
 }
@@ -164,9 +184,35 @@ export async function rewardUpdate(input) {
         payload.levels = input.levels;
     if (input.segments !== undefined)
         payload.segments = input.segments;
-    // usageLimit - only pass perUser (API rejects 'general' as extra field)
+    // usageLimit handling depends on reward type:
+    //   - material/fortune_wheel: require BOTH perUser AND general
+    //   - coupon types: only accept perUser (general is rejected as "extra fields")
+    const existingRewardType = existing.reward;
+    const isCouponType = ["static_coupon", "dynamic_coupon", "conversion_coupon"].includes(existingRewardType || "");
+    const existingUsageLimit = existing.usageLimit;
     if (input.usageLimitPerUser !== undefined) {
-        payload.usageLimit = { perUser: input.usageLimitPerUser };
+        // User explicitly setting usageLimitPerUser
+        if (isCouponType) {
+            payload.usageLimit = { perUser: input.usageLimitPerUser };
+        }
+        else {
+            payload.usageLimit = {
+                perUser: input.usageLimitPerUser,
+                general: existingUsageLimit?.general ?? 0,
+            };
+        }
+    }
+    else if (existingUsageLimit) {
+        // Preserve existing usageLimit (API requires it on PUT for material type)
+        if (isCouponType) {
+            payload.usageLimit = { perUser: existingUsageLimit.perUser ?? 0 };
+        }
+        else {
+            payload.usageLimit = {
+                perUser: existingUsageLimit.perUser ?? 0,
+                general: existingUsageLimit.general ?? 0,
+            };
+        }
     }
     try {
         await apiPut(`/${storeCode}/reward/${input.rewardId}`, { reward: payload });

package/dist/tools/reward/index.d.ts

@@ -68,6 +68,8 @@ export declare const rewardToolDefinitions: readonly [{
             from: string;
             to: string;
         }>;
+        usageLimitPerUser: import("zod").ZodOptional<import("zod").ZodNumber>;
+        usageLimitGeneral: import("zod").ZodOptional<import("zod").ZodNumber>;
         costInPoints: import("zod").ZodOptional<import("zod").ZodNumber>;
         usageInstruction: import("zod").ZodOptional<import("zod").ZodString>;
         active: import("zod").ZodOptional<import("zod").ZodBoolean>;

package/dist/tools/reward/index.js

@@ -20,15 +20,19 @@ export const rewardToolDefinitions = [
         name: "ol_reward_create",
         title: "Create New Reward",
         description: "Create a new reward that members can redeem with points. " +
-            "⚠️ REQUIRED FIELDS (will fail without these): " +
+            "REQUIRED FIELDS: " +
             "1. translations: { en: { name: 'Reward Name' } }, " +
-            "2. reward: 'material' or 'static_coupon' or 'dynamic_coupon', " +
+            "2. reward: 'material' or 'static_coupon' or 'dynamic_coupon' or 'conversion_coupon' or 'fortune_wheel', " +
             "3. activity: { from: '2026-01-01 00:00', to: '2027-12-31 23:59' }, " +
             "4. visibility: { from: '2026-01-01 00:00', to: '2027-12-31 23:59' }. " +
-            "Types: material (physical goods), static_coupon (fixed discount - requires couponValue), dynamic_coupon (variable value). " +
-            "For coupons: add couponValue (required!), couponValueType ('money' or 'percentage'), daysValid. " +
-            "For tier targeting: set target='level' and levels=['tier-uuid-1', 'tier-uuid-2']. " +
-            "⚠️ usageLimit is NOT supported at creation - use reward_update after creation to set limits.",
+            "WARNING: 'discount_code' is NOT a valid type - use 'static_coupon' instead. " +
+            "USAGE LIMITS by type: " +
+            "- material/fortune_wheel: usageLimitPerUser + usageLimitGeneral (both sent, default 0 = unlimited). " +
+            "- static_coupon/dynamic_coupon/conversion_coupon: ONLY usageLimitPerUser (do NOT set usageLimitGeneral - API rejects it). " +
+            "TYPE-SPECIFIC requirements: " +
+            "- static_coupon: couponValue is REQUIRED (e.g., couponValue: 10). " +
+            "- conversion_coupon: unitsConversion.ratio and unitsConversion.rounding are REQUIRED. " +
+            "For tier targeting: set target='level' and levels=['tier-uuid-1', 'tier-uuid-2'].",
         readOnly: false,
         inputSchema: RewardCreateInputSchema,
         handler: rewardCreate,
@@ -45,7 +49,9 @@ export const rewardToolDefinitions = [
         name: "ol_reward_update",
         title: "Update Reward",
         description: "Update reward configuration. Cannot change reward type after creation. " +
-            "Use usageLimitPerUser to set maximum redemptions per member (this is NOT supported at creation time).",
+            "Uses GET-then-PUT pattern (fetches existing reward, merges changes, sends full object). " +
+            "usageLimitPerUser can be set here or at creation time. " +
+            "For material rewards, usageLimit.general is preserved from existing data on update.",
         readOnly: false,
         inputSchema: RewardUpdateInputSchema,
         handler: rewardUpdate,

package/dist/tools/reward/schemas.d.ts

@@ -55,6 +55,8 @@ export declare const RewardCreateInputSchema: {
         from: string;
         to: string;
     }>;
+    usageLimitPerUser: z.ZodOptional<z.ZodNumber>;
+    usageLimitGeneral: z.ZodOptional<z.ZodNumber>;
     costInPoints: z.ZodOptional<z.ZodNumber>;
     usageInstruction: z.ZodOptional<z.ZodString>;
     active: z.ZodOptional<z.ZodBoolean>;

package/dist/tools/reward/schemas.js

@@ -26,16 +26,26 @@ const RewardVisibilityInputSchema = z.object({
     from: z.string().describe("Visibility start datetime (format: 'YYYY-MM-DD HH:mm'). REQUIRED."),
     to: z.string().describe("Visibility end datetime (format: 'YYYY-MM-DD HH:mm'). REQUIRED."),
 });
-// NOTE: usageLimit is NOT supported at creation time - API rejects it as "extra fields"
-// Use reward_update with usageLimitPerUser after creation instead
+// NOTE: usageLimit shape depends on reward TYPE:
+//   - material/fortune_wheel: require BOTH perUser AND general
+//   - coupon types (static_coupon, dynamic_coupon, conversion_coupon): only accept perUser
+// Handler automatically sends the correct shape based on reward type.
 export const RewardCreateInputSchema = {
     storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
     translations: RewardTranslationsInputSchema.describe("Reward name translations. At least 'en' key with { name } is REQUIRED."),
-    reward: z.enum(["static_coupon", "dynamic_coupon", "conversion_coupon", "material", "fortune_wheel"]).describe("Reward type: static_coupon (fixed discount), dynamic_coupon (variable value), " +
-        "conversion_coupon (converts points to coupon), material (physical goods), fortune_wheel (gamified)."),
+    reward: z.enum(["static_coupon", "dynamic_coupon", "conversion_coupon", "material", "fortune_wheel"]).describe("Reward type. Valid values: " +
+        "'material' (physical goods like merchandise, experiences), " +
+        "'static_coupon' (fixed discount code - requires couponValue), " +
+        "'dynamic_coupon' (variable value coupon), " +
+        "'conversion_coupon' (converts points to coupon - requires unitsConversion), " +
+        "'fortune_wheel' (gamified reward). " +
+        "WARNING: 'discount_code' is NOT valid - use 'static_coupon' instead."),
     activity: RewardActivityInputSchema.describe("Activity period when reward can be purchased. Use datetime format 'YYYY-MM-DD HH:mm'. REQUIRED."),
     visibility: RewardVisibilityInputSchema.describe("Visibility period when reward is shown. Use datetime format 'YYYY-MM-DD HH:mm'. REQUIRED."),
-    // usageLimit: NOT SUPPORTED at creation - removed. Use reward_update after creation.
+    usageLimitPerUser: z.number().optional().describe("Max redemptions per member (default: 0 = unlimited). Applies to ALL reward types."),
+    usageLimitGeneral: z.number().optional().describe("Max total redemptions across all members (default: 0 = unlimited). " +
+        "ONLY for 'material' and 'fortune_wheel' types. " +
+        "Do NOT set this for coupon types (static_coupon, dynamic_coupon, conversion_coupon) - API will reject it."),
     costInPoints: z.number().optional().describe("Points required to redeem this reward."),
     usageInstruction: z.string().optional().describe("Instructions for using the reward."),
     active: z.boolean().optional().describe("Whether reward is active (default: false)."),

package/dist/tools/tierset.d.ts

@@ -218,7 +218,7 @@ export declare const tiersetToolDefinitions: readonly [{
 }, {
     readonly name: "ol_tierset_update_tiers";
     readonly title: "Configure Tier Thresholds";
-    readonly description: "Define tier thresholds for a tier set. PREREQUISITE: Call tierset_get first to obtain conditionId values. Each tier's conditions array uses conditionId from the parent tier set plus a threshold value.\n\nExample for a 3-tier program with points-based progression:\n- Bronze tier: conditions: [{ conditionId: \"xxx\", value: 400 }]\n- Silver tier: conditions: [{ conditionId: \"xxx\", value: 800 }]\n- Gold tier: conditions: [{ conditionId: \"xxx\", value: 1200 }]\n\nThe conditionId must match one from tierset_get response.";
+    readonly description: "Add ALL tiers to a tier set in ONE call. A tier set is a CONTAINER - add all tiers (Bronze, Silver, Gold, etc.) to it together.\n\n⚠️ CRITICAL: Pass ALL tiers in a SINGLE call to this endpoint. DO NOT call this multiple times with one tier each.\n\n⚠️ INPUT FORMAT: Pass 'name' and 'description' as TOP-LEVEL fields on each tier object.\n❌ WRONG: { translations: { en: { name: \"Bronze\" } } }\n✅ CORRECT: { name: \"Bronze\", description: \"Entry tier\" }\n\nExample - Creating 4 tiers in ONE call:\ntiers: [\n  { name: \"Bronze\", description: \"Entry tier\", conditions: [{ conditionId: \"xxx\", value: 0 }] },\n  { name: \"Silver\", description: \"500+ points\", conditions: [{ conditionId: \"xxx\", value: 500 }] },\n  { name: \"Gold\", description: \"1000+ points\", conditions: [{ conditionId: \"xxx\", value: 1000 }] },\n  { name: \"Platinum\", description: \"Top tier\", conditions: [{ conditionId: \"xxx\", value: 2000 }] }\n]\n\nThe conditionId must match the one from tierset_get response - use the SAME conditionId for all tiers.";
     readonly readOnly: false;
     readonly inputSchema: {
         storeCode: z.ZodOptional<z.ZodString>;

package/dist/tools/tierset.js

@@ -42,14 +42,14 @@ export const TierSetUpdateTiersInputSchema = {
     tierSetId: z.string().describe("The tier set ID to update tiers for."),
     tiers: z.array(z.object({
         levelId: z.string().optional().describe("Existing level ID (for updates). Omit for new tiers."),
-        name: z.string().describe("Name of the tier (e.g., Bronze, Silver, Gold)."),
-        description: z.string().optional().describe("Description of the tier."),
+        name: z.string().describe("Tier name as a TOP-LEVEL string (e.g., 'Bronze'). NOT in translations wrapper."),
+        description: z.string().optional().describe("Tier description as a TOP-LEVEL string. NOT in translations wrapper."),
         active: z.boolean().optional().describe("Whether the tier is active. Defaults to true."),
         conditions: z.array(z.object({
             conditionId: z.string().describe("Condition ID from tierset_get response."),
             value: z.number().describe("Threshold value for this condition (e.g., 400 points for Bronze)."),
         })).describe("Array of condition thresholds. Each uses conditionId from tierset_get."),
-    })).describe("Array of tier definitions."),
+    })).describe("Array of tier definitions. Each tier needs 'name' as a direct string field, NOT wrapped in translations."),
 };
 export const TierSetGetTiersInputSchema = {
     storeCode: z.string().optional().describe("Store code for multi-tenant routing. DO NOT pass this parameter - the configured default will be used automatically. Only provide a value if the user explicitly asks to work with a different store."),
@@ -90,14 +90,30 @@ export async function tiersetCreate(input) {
     // REQUIRED fields:
     // - translations.en.name (string)
     // - conditions (array with attribute, optionally walletType)
+    //
+    // IMPORTANT: Only include description if actually provided - API rejects empty string as "extra field"
+    const enTranslation = {
+        name: input.name,
+    };
+    if (input.description) {
+        enTranslation.description = input.description;
+    }
+    // Explicitly map conditions to only include known fields (attribute + walletType)
+    // This strips any extra fields that might slip through Zod validation
+    const mappedConditions = input.conditions.map((c) => {
+        const condition = {
+            attribute: c.attribute,
+        };
+        if (c.walletType) {
+            condition.walletType = c.walletType;
+        }
+        return condition;
+    });
     const tierSetPayload = {
         translations: {
-            en: {
-                name: input.name,
-                description: input.description || "",
-            },
+            en: enTranslation,
         },
-        conditions: input.conditions,
+        conditions: mappedConditions,
     };
     const payload = { tierSet: tierSetPayload };
     try {
@@ -220,8 +236,8 @@ export const tiersetToolDefinitions = [
     {
         name: "ol_tierset_list",
         title: "List Loyalty Programs",
-        description: "List all tier sets. RECOMMENDED: Check if tier set already exists before creating a new one. " +
-            "If exists, use tierset_get to fetch conditionId needed for defining tiers via tierset_update_tiers. " +
+        description: "List all tier sets. A tier set is a CONTAINER that holds MULTIPLE tiers (e.g., Bronze/Silver/Gold). " +
+            "⚠️ ALWAYS check existing tier sets FIRST before creating - reuse if one exists. " +
             "Returns tierSetId, name, active status, and tier count for each tier set.",
         readOnly: true,
         inputSchema: TierSetListInputSchema,
@@ -230,13 +246,13 @@ export const tiersetToolDefinitions = [
     {
         name: "ol_tierset_create",
         title: "Create Loyalty Program",
-        description: "Create a new tier set (loyalty program structure). " +
-            "⚠️ LIMIT: Maximum 3 ACTIVE tier sets per store. ALWAYS call tierset_list FIRST to check existing tier sets - if one exists that matches your needs, REUSE IT instead of creating a new one. " +
-            "WORKFLOW: 1) tierset_list (check existing) → 2) tierset_create (only if needed) → 3) tierset_get (to get conditionId) → 4) tierset_update_tiers (to define thresholds). " +
+        description: "Create ONE tier set that will contain ALL your tiers (e.g., Bronze/Silver/Gold/Platinum). " +
+            "⚠️ CRITICAL: Create exactly ONE tier set, then add ALL tiers to it via tierset_update_tiers. " +
+            "DO NOT create multiple tier sets for different tiers - all tiers belong in ONE tier set! " +
+            "⚠️ LIMIT: Maximum 3 ACTIVE tier sets per store. ALWAYS call tierset_list FIRST to check existing tier sets. " +
+            "WORKFLOW: 1) tierset_list → 2) tierset_create (ONE tier set) → 3) tierset_get (get conditionId) → 4) tierset_update_tiers (add ALL tiers in one call). " +
             "⚠️ API LIMITATION: Only 'name', 'description', and 'conditions' are accepted at creation time. " +
-            "Fields like 'active', 'downgrade', 'tiers' are NOT supported at creation - use tierset_update after creation to set these. " +
-            "Valid condition attributes: 'totalEarnedUnits' (lifetime points), 'activeUnits' (current balance), 'totalSpending', 'monthsSinceJoiningProgram'. " +
-            "COMMON MISTAKE: Use 'totalEarnedUnits' NOT 'earnedUnits' for lifetime points. " +
+            "Valid condition attributes: 'totalEarnedUnits' (lifetime points), 'activeUnits' (current balance), 'totalSpending'. " +
             "For unit-based attributes, set walletType to 'default'.",
         readOnly: false,
         inputSchema: TierSetCreateInputSchema,
@@ -246,9 +262,8 @@ export const tiersetToolDefinitions = [
         name: "ol_tierset_get",
         title: "Get Loyalty Program Details",
         description: "Get tier set details including conditionId values needed for tierset_update_tiers. " +
-            "CRITICAL: After tierset_create, you MUST call this to get the conditionId from the conditions array. " +
-            "The conditionId is then used in tierset_update_tiers to set tier thresholds. " +
-            "Response includes conditions[].id (this is the conditionId) and conditions[].attribute.",
+            "CRITICAL: After tierset_create, call this to get the conditionId from conditions[].id. " +
+            "Use this SAME conditionId for ALL tiers when calling tierset_update_tiers.",
         readOnly: true,
         inputSchema: TierSetGetInputSchema,
         handler: tiersetGet,
@@ -266,14 +281,23 @@ export const tiersetToolDefinitions = [
     {
         name: "ol_tierset_update_tiers",
         title: "Configure Tier Thresholds",
-        description: `Define tier thresholds for a tier set. PREREQUISITE: Call tierset_get first to obtain conditionId values. Each tier's conditions array uses conditionId from the parent tier set plus a threshold value.
+        description: `Add ALL tiers to a tier set in ONE call. A tier set is a CONTAINER - add all tiers (Bronze, Silver, Gold, etc.) to it together.
+
+⚠️ CRITICAL: Pass ALL tiers in a SINGLE call to this endpoint. DO NOT call this multiple times with one tier each.
+
+⚠️ INPUT FORMAT: Pass 'name' and 'description' as TOP-LEVEL fields on each tier object.
+❌ WRONG: { translations: { en: { name: "Bronze" } } }
+✅ CORRECT: { name: "Bronze", description: "Entry tier" }
 
-Example for a 3-tier program with points-based progression:
-- Bronze tier: conditions: [{ conditionId: "xxx", value: 400 }]
-- Silver tier: conditions: [{ conditionId: "xxx", value: 800 }]
-- Gold tier: conditions: [{ conditionId: "xxx", value: 1200 }]
+Example - Creating 4 tiers in ONE call:
+tiers: [
+  { name: "Bronze", description: "Entry tier", conditions: [{ conditionId: "xxx", value: 0 }] },
+  { name: "Silver", description: "500+ points", conditions: [{ conditionId: "xxx", value: 500 }] },
+  { name: "Gold", description: "1000+ points", conditions: [{ conditionId: "xxx", value: 1000 }] },
+  { name: "Platinum", description: "Top tier", conditions: [{ conditionId: "xxx", value: 2000 }] }
+]
 
-The conditionId must match one from tierset_get response.`,
+The conditionId must match the one from tierset_get response - use the SAME conditionId for all tiers.`,
         readOnly: false,
         inputSchema: TierSetUpdateTiersInputSchema,
         handler: tiersetUpdateTiers,

package/dist/tools/transaction.js

@@ -10,14 +10,14 @@ const LabelInputSchema = z.object({
 });
 const TransactionHeaderInputSchema = z.object({
     documentNumber: z.string().describe("Unique document number (required, unique per store)."),
-    purchasedAt: z.string().describe("Purchase date/time in ISO format (required)."),
+    purchasedAt: z.string().describe("Purchase date/time in ISO format (required). Use 'purchasedAt' NOT 'purchaseDate'. Example: '2026-01-15T10:00:00Z'."),
     documentType: z.enum(["sell", "return"]).optional().describe("Document type: sell (default) or return."),
     linkedDocumentNumber: z.string().optional().describe("Original document number (required for returns)."),
     purchasePlace: z.string().optional().describe("Location/store where purchase was made."),
     labels: z.array(LabelInputSchema).optional().describe("Custom key-value labels."),
 });
 const TransactionItemInputSchema = z.object({
-    sku: z.string().describe("Product SKU (required, max 255 chars)."),
+    sku: z.string().describe("Product SKU as a STRING (required). Use 'sku: \"PROD-123\"' NOT 'sku: { code: \"...\" }'."),
     name: z.string().describe("Product name (required, max 255 chars)."),
     grossValue: z.number().describe("Item gross value (required)."),
     category: z.string().describe("Product category (required, max 255 chars)."),
@@ -219,6 +219,9 @@ export const transactionToolDefinitions = [
         title: "Record Purchase",
         description: "Record a purchase transaction. If customerData provided, auto-matches to member and triggers point campaigns. " +
             "For returns, set documentType='return' and provide linkedDocumentNumber referencing original sale. " +
+            "⚠️ FIELD NAMES - use exactly these: " +
+            "header.purchasedAt (NOT purchaseDate), items[].sku as STRING (NOT object). " +
+            "Example: { header: { documentNumber: 'INV-001', purchasedAt: '2026-01-15T10:00:00Z' }, items: [{ sku: 'PROD-123', name: 'Product', grossValue: 50, category: 'Sales' }] }. " +
             "Returns transactionId and pointsEarned if campaigns triggered.",
         readOnly: false,
         inputSchema: TransactionCreateInputSchema,

package/dist/tools/wallet-type.js

@@ -138,11 +138,18 @@ export async function walletTypeCreate(input) {
         // Check for duplicate code error
         const errorMsg = getErrorMessage(error);
         if (errorMsg.toLowerCase().includes("code") && errorMsg.toLowerCase().includes("already")) {
+            const isDefaultCode = input.code === "default" || !input.code;
             throw new OpenLoyaltyError({
                 code: "DUPLICATE_CODE",
-                message: `Wallet type with code '${input.code}' already exists`,
-                hint: `Use a different code value, or use ol_wallet_type_list() to find existing wallet types. ` +
-                    `Each wallet type must have a unique code.`,
+                message: `Wallet type with code '${input.code || "default"}' already exists`,
+                hint: isDefaultCode
+                    ? `Every store comes with a 'Default wallet' (code: 'default') pre-installed. ` +
+                        `You do NOT need to create it. Use ol_wallet_type_list() to find it, then ` +
+                        `ol_wallet_type_update() to customize its name, units, or expiry settings. ` +
+                        `Only create a new wallet if you need a SECOND point currency with a different code.`
+                    : `A wallet type with code '${input.code}' already exists. ` +
+                        `Use ol_wallet_type_list() to see all existing wallet types. ` +
+                        `Either use a different code, or find the existing wallet and update it with ol_wallet_type_update().`,
                 relatedTool: "ol_wallet_type_create",
             });
         }
@@ -231,9 +238,9 @@ export const walletTypeToolDefinitions = [
         name: "ol_wallet_type_list",
         title: "List Point Currencies",
         description: "List all available wallet types (point currencies). " +
-            "Use this to find wallet type codes and IDs for other operations. " +
-            "Returns walletTypeId (UUID), code (unique identifier like 'default'), and name for each wallet type. " +
-            "💡 TIP: Most stores have a 'default' wallet type for main loyalty points.",
+            "ALWAYS call this BEFORE creating a new wallet type - every store already has a 'Default wallet' " +
+            "(code: 'default', units: points) pre-installed. " +
+            "Returns walletTypeId (UUID), code (unique identifier like 'default'), and name for each wallet type.",
         readOnly: true,
         inputSchema: WalletTypeListInputSchema,
         handler: walletTypeList,
@@ -252,21 +259,23 @@ export const walletTypeToolDefinitions = [
         name: "ol_wallet_type_create",
         title: "Create Point Currency",
         description: "Create a new wallet type (point currency) for the loyalty program. " +
-            "⚠️ REQUIRED FIELDS (will fail without these): " +
+            "IMPORTANT: Every store already has a 'Default wallet' (code: 'default', units: points) out of the box. " +
+            "ALWAYS call ol_wallet_type_list() FIRST to check what wallets exist before creating a new one. " +
+            "If the default wallet fits your needs, use it as-is or update it with ol_wallet_type_update(). " +
+            "Only create a new wallet if you need a SECOND currency (e.g., 'stars', 'coins', 'miles'). " +
+            "REQUIRED FIELDS (will fail without these): " +
             "1. translations: { en: { name: 'Currency Name' } } - Name is REQUIRED. " +
             "2. unitSingularName: 'point' (or 'coin', 'star', etc.) - The singular form. " +
             "3. unitPluralName: 'points' (or 'coins', 'stars', etc.) - The plural form. " +
             "4. unitDaysExpiryAfter: 'all_time_active' or number string like '365'. " +
-            "📝 OPTIONAL: " +
-            "• code: Unique identifier (auto-generated if omitted, cannot change later). " +
-            "• allowNegativeBalance: true/false (default: false). " +
-            "• unitExpiryDate: Annual expiry in 'MM-DD' format (e.g., '12-31'). " +
-            "• allTimeNotLocked: TRUE = 'No pending' (points immediately available). " +
-            "• unitDaysLocked: Only if allTimeNotLocked=false, set days for pending period. " +
-            "⚠️ NOT SUPPORTED AT CREATION: 'active' and 'limits' - use ol_wallet_type_update after creation. " +
-            "⏰ NOTE: New wallets are 'blocked' for ~2 minutes after creation - wait before updating. " +
-            "💡 EXAMPLE: { translations: { en: { name: 'Bonus Points' } }, unitSingularName: 'point', " +
-            "unitPluralName: 'points', unitDaysExpiryAfter: 'all_time_active', code: 'bonus' }",
+            "OPTIONAL: " +
+            "code: Unique identifier (auto-generated if omitted, cannot change later). " +
+            "allowNegativeBalance: true/false (default: false). " +
+            "unitExpiryDate: Annual expiry in 'MM-DD' format (e.g., '12-31'). " +
+            "allTimeNotLocked: TRUE = 'No pending' (points immediately available). " +
+            "unitDaysLocked: Only if allTimeNotLocked=false, set days for pending period. " +
+            "NOT SUPPORTED AT CREATION: 'active' and 'limits' - use ol_wallet_type_update after creation. " +
+            "NOTE: New wallets are 'blocked' for ~2 minutes after creation - wait before updating.",
         readOnly: false,
         inputSchema: WalletTypeCreateInputSchema,
         handler: walletTypeCreate,