Version: v0.5.0 Purpose: User-friendly guide to KidsChores service actions for automations and scripts

KidsChores provides 22 service actions that allow you to automate workflows, integrate with external systems, and manage the chore economy programmatically. All services are available under the kidschores domain.

Service Categories:

• Chore Workflow: Claim, approve, disapprove chores
• Rewards & Economy: Redeem, approve rewards; apply bonuses/penalties
• CRUD Management: Create, update, delete chores and rewards
• Scheduling: Set due dates, skip chores, reset overdue items
• Maintenance: Reset chores, clear data, manage badges
• Admin: Shadow kid linking, system resets

Purpose: Mark a chore as claimed by a kid.

Parameters:

Authorization:

• Dashboard Button: If triggered by a user (e.g., Dashboard button press), the user must be linked to the Kid profile or be an Admin.
• Automation Context: Automations running in the background (System context) bypass this check and can claim chores freely.

Example:

action: kidschores.claim_chore
data:
  chore_name: "Make Bed"
  kid_name: "Sarah"

Use Cases:

• NFC tag automation (kid taps tag to claim chore)
• Voice command integration ("Alexa, claim dishes")
• Scheduled auto-claim for routine tasks

Purpose: Approve a chore, award points, and advance the schedule.

Parameters:

Authorization: Parent/admin only.

Points Override Feature:

• If points_awarded is provided, it overrides the chore's default point value for this specific completion
• Constraint: Points override must be a positive number (> 0)
• Use cases: Award partial points for "good enough" work, or bonus points for exceptional speed
• Example: Chore configured for 10 points, but parent awards 5 points for rushed job

One-Click Behavior:

Example:

# Standard approval
action: kidschores.approve_chore
data:
  parent_name: "Mom"
  chore_name: "Wash Dishes"
  kid_name: "Alex"

# Approval with point override
action: kidschores.approve_chore
data:
  parent_name: "Dad"
  chore_name: "Clean Room"
  kid_name: "Sarah"
  points_awarded: 7.5  # Partial credit

Use Cases:

• Automatic approval based on sensor data (motion sensor confirms room cleaned)
• Scheduled approval for recurring low-stakes chores
• Point adjustments for quality of work

Purpose: Reject a chore claim or completion, reverting state to pending.

Parameters:

Authorization: Parent/admin only.

Shared First Reset:

Example:

action: kidschores.disapprove_chore
data:
  parent_name: "Dad"
  chore_name: "Take Out Trash"
  kid_name: "Alex"

Use Cases:

• Undo accidental approvals
• Re-open Shared First chores when winner's work is unsatisfactory
• Reset chores when quality standards not met

Purpose: Kid requests to claim a reward (spends points).

Parameters:

Authorization: Kid or admin.

Balance Check:

Points Deduction: Points are only deducted when parent approves the reward via approve_reward. Redeeming puts the reward in a pending state.

Example:

action: kidschores.redeem_reward
data:
  parent_name: "Mom"
  reward_name: "Movie Night"
  kid_name: "Alex"

Purpose: Parent approves a reward redemption, deducting points.

Parameters:

Cost Override Feature:

• If cost_override is provided, it replaces the reward's configured cost for this redemption
• Use Cases:
  • Weekend discount pricing (e.g., 50% off rewards on Saturdays)
  • Birthday/special occasion free grants (set to 0)
  • Context-aware automation pricing via calendar events
  • "Buy one get one" promotions
• Example: Reward normally costs 20 points, but automation sets cost_override: 10 during "Happy Hour"

Purpose: Parent rejects a reward redemption.

Parameters:

Authorization: Parent/admin only.

Points Deduction: Points are deducted from kid's balance only on approval. Disapproval cancels the redemption without affecting points.

Example:

# Standard approval
action: kidschores.approve_reward
data:
  parent_name: "Mom"
  reward_name: "Extra Screen Time"
  kid_name: "Sarah"

# Approval with cost override (birthday free grant)
action: kidschores.approve_reward
data:
  parent_name: "Dad"
  reward_name: "Special Toy"
  kid_name: "Alex"
  cost_override: 0  # Birthday gift - no points deducted

# Approval with discount pricing
action: kidschores.approve_reward
data:
  parent_name: "Mom"
  reward_name: "Movie Night"
  kid_name: "Sarah"
  cost_override: 15  # 50% weekend discount from normal 30 points

# Reject reward
action: kidschores.disapprove_reward
data:
  parent_name: "Mom"
  reward_name: "Extra Screen Time"
  kid_name: "Sarah"

Purpose: Manually adjust kid's points outside the chore system.

Parameters:

Logic:

• apply_bonus: Adds points to kid's balance
• apply_penalty: Deducts points (converts positive input to negative internally)

Metadata Tracking: These actions log to penalty_applies and bonus_applies counters, visible in dashboard helpers and sensors.

Example:

# Award bonus points
action: kidschores.apply_bonus
data:
  parent_name: "Mom"
  kid_name: "Sarah"
  bonus_name: "Extra Helpful"

# Apply penalty
action: kidschores.apply_penalty
data:
  parent_name: "Dad"
  kid_name: "Alex"
  penalty_name: "Yelling"

Use Cases:

• Good behavior rewards outside chore system
• Consequences for rule violations
• Special event bonuses (birthdays, holidays)

Purpose: Set or clear the due date for a chore dynamically.

Parameters:

Independent vs Shared Chores:

• Independent Chores: If kid_name is provided, only that kid's due date is updated. Other kids maintain their own schedules.
• Shared Chores: kid_name parameter is not allowed. Shared chores must have a global due date.

Past Date Validation: The service will reject due dates in the past with an error.

Clearing Due Dates: Send an empty due_date parameter to remove the deadline.

Example:

# Set due date for Independent chore (specific kid)
action: kidschores.set_chore_due_date
data:
  chore_name: "Clean Room"
  due_date: "2025-02-15T18:00:00Z"
  kid_name: "Sarah"

# Set due date for Shared chore (all kids)
action: kidschores.set_chore_due_date
data:
  chore_name: "Take Out Trash"
  due_date: "2025-02-14T08:00:00Z"

# Clear due date
action: kidschores.set_chore_due_date
data:
  chore_name: "Pick Up Sticks"

Use Cases:

1. One-Time Chores: Assign due dates to non-recurring tasks like "Pick up sticks in yard"
2. Calendar-Based Automation: Sync chore due dates with calendar events (e.g., trash pickup day changes weekly)
3. Dynamic Scheduling: Adjust deadlines based on family schedule changes

Interaction with Recurrence:

• No Recurrence: Due date applies once. After approval, due date clears automatically.
• With Recurrence: Due date updates per normal recurrence pattern after completion.

Interaction with States:

• Pending Chore: Stays pending until due date reached
• Approved Chore: Remains approved until due date, then resets automatically

Purpose: Advance a recurring chore to its next scheduled slot without awarding points (skip today).

Parameters:

Requirement: The chore must have a Recurring Frequency (Daily, Weekly, etc.). Skipping a one-time chore (Frequency: None) will fail or do nothing because there is no "next" date to calculate.

Logic:

1. Calculates next_due based on chore's Frequency + Applicable Days
2. Updates the due date to next occurrence
3. Resets state to pending

Example:

# Skip by chore name
action: kidschores.skip_chore_due_date
data:
  chore_name: "Daily Reading"
  kid_name: "Sarah"

# Skip by chore ID (advanced)
action: kidschores.skip_chore_due_date
data:
  chore_id: "abc-123-def"
  kid_name: "Sarah"

Use Cases:

• "Skip today" dashboard buttons for sick days
• Holiday automation (skip all daily chores on Christmas)
• Temporary schedule adjustments

Purpose: Force overdue chores back to pending state and reschedule them to their next occurrence.

Parameters:

Flexible Targeting:

Completion Criteria Interaction:

Independent Chores:

• Each kid has their own schedule and state
• Resetting one kid's chore does NOT affect other kids
• Example: Sarah's "Make Bed" is overdue, Alex's "Make Bed" stays untouched

Shared Chores:

• Single chore instance with global due date
• Resetting affects all assigned kids (resets to pending for everyone)
• Example: "Take Out Trash" shared by Sarah and Alex → reset puts both kids back to pending

Shared First Chores:

• Winner's completion locks out other kids
• If winner's chore is overdue and reset, all kids become eligible again
• Example: Alex won "First to Feed Dog" but went overdue → reset reopens race for Sarah and Alex

Multi-Approval Chores:

• Each kid must complete independently
• Resetting one kid's completion does NOT affect others
• Example: "Walk Dog Together" requires 2 approvals → resetting Sarah's portion leaves Alex's approval intact

Example:

# Reset specific chore for all kids
action: kidschores.reset_overdue_chores
data:
  chore_name: "Wash Dishes"

# Reset all overdue chores for one kid
action: kidschores.reset_overdue_chores
data:
  kid_name: "Sarah"

# Reset specific chore for specific kid
action: kidschores.reset_overdue_chores
data:
  chore_name: "Make Bed"
  kid_name: "Alex"

# Global reset (all overdue chores)
action: kidschores.reset_overdue_chores
data: {}

Use Cases:

• Weekly automation to clear overdue items (fresh start Sundays)
• Dashboard button for parents to bulk-reset overdue chores
• Integration with notification system (reset after reminder sent)

Purpose: Create a new chore programmatically.

Parameters:

Authorization: Parent/admin only.

Returns: {"chore_id": "abc-123-def-456"} - The internal ID of the created chore.

Example:

action: kidschores.create_chore
data:
  name: "Weekly Garden Cleanup"
  assigned_kids: ["Emma", "Jack"]
  points: 20
  description: "Weed garden beds and water plants"
  icon: "mdi:flower"
  labels: ["outdoor", "garden"]
  frequency: "weekly"
  applicable_days: ["sat"]

Use Cases:

• Seasonal chore creation (spring cleaning, leaf raking)
• Dynamic chore assignment based on kids' ages/capabilities
• Integration with external task management systems

Purpose: Update an existing chore's properties. Only provided fields will be updated.

Parameters:

Identification: Provide either id OR name to identify the chore to update.

Authorization: Parent/admin only.

Returns: {"chore_id": "abc-123-def-456"} - The internal ID of the updated chore.

Example:

# Update by name
action: kidschores.update_chore
data:
  name: "Clean Room"
  points: 15
  frequency: "daily"

# Update by ID
action: kidschores.update_chore
data:
  id: "abc-123-def-456"
  assigned_kids: ["Emma", "Jack", "Sophie"]
  description: "Deep clean with vacuum and dusting"

Use Cases:

• Adjust point values based on difficulty/time observations
• Reassign chores when kids' schedules change
• Modify frequency as habits develop or seasons change

Purpose: Permanently delete a chore and all its history.

Parameters:

Identification: Provide either id OR name to identify the chore to delete.

Authorization: Parent/admin only.

Warning: This permanently deletes the chore and ALL associated history (completions, points earned, streaks). Cannot be undone.

Returns: {"deleted_chore_id": "abc-123-def-456", "message": "Chore deleted successfully"}

Example:

# Delete by name
action: kidschores.delete_chore
data:
  name: "Summer Pool Cleaning"

# Delete by ID
action: kidschores.delete_chore
data:
  id: "abc-123-def-456"

Use Cases:

• Remove seasonal/temporary chores (pool maintenance, holiday decorations)
• Clean up duplicate or test chores
• Archive completed one-time tasks

Purpose: Create a new reward programmatically.

Parameters:

Authorization: Parent/admin only.

Returns: {"reward_id": "def-456-ghi-789"} - The internal ID of the created reward.

Example:

action: kidschores.create_reward
data:
  name: "Extra Screen Time"
  cost: 25
  description: "30 minutes of additional screen time"
  icon: "mdi:television"
  labels: ["screen", "bonus"]

Use Cases:

• Seasonal rewards (summer activities, holiday treats)
• Dynamic reward pricing based on point inflation/deflation
• Integration with external reward fulfillment systems

Purpose: Update an existing reward's properties. Only provided fields will be updated.

Parameters:

Identification: Provide either id OR name to identify the reward to update.

Authorization: Parent/admin only.

Returns: {"reward_id": "def-456-ghi-789"} - The internal ID of the updated reward.

Example:

# Update by name
action: kidschores.update_reward
data:
  name: "Extra Screen Time"
  cost: 20
  description: "45 minutes of additional screen time"

# Update by ID
action: kidschores.update_reward
data:
  id: "def-456-ghi-789"
  cost: 40
  labels: ["premium", "special"]

Use Cases:

• Adjust reward pricing based on redemption patterns
• Update seasonal availability or descriptions
• Modify reward tiers as kids mature

Purpose: Permanently delete a reward and all its history.

Parameters:

Identification: Provide either id OR name to identify the reward to delete.

Authorization: Parent/admin only.

Warning: This permanently deletes the reward and ALL associated history (redemptions, approvals). Cannot be undone.

Returns: {"deleted_reward_id": "def-456-ghi-789", "message": "Reward deleted successfully"}

Example:

# Delete by name
action: kidschores.delete_reward
data:
  name: "Summer Pool Pass"

# Delete by ID
action: kidschores.delete_reward
data:
  id: "def-456-ghi-789"

Use Cases:

• Remove seasonal/expired rewards (pool passes, event tickets)
• Clean up duplicate or test rewards
• Archive rewards that are no longer relevant

Purpose: Soft reset - set all chores to pending state without clearing history or points.

Parameters: None (no data required)

Logic:

• Resets ALL chores to pending state
• Resets approval_period_start to current time
• Does NOT clear points, history, or streak data

Example:

action: kidschores.reset_chores_to_pending_state
data: {}

Use Cases:

• Fix desynchronized schedule (chores stuck in wrong states)
• Fresh start after vacation
• Debugging automation issues

Purpose: Reset runtime/transactional data while preserving configuration (kids, chores, rewards, etc.).

Parameters:

Safety Features:

Scope Options:

Item Type Filters:

• chores - Reset chore states, claims, completions
• rewards - Reset reward redemptions
• penalties - Reset penalty applications
• bonuses - Reset bonus applications
• points - Reset point balances
• Leave empty to reset all transactional data

Example:

# Global reset (all kids, all data)
action: kidschores.reset_transactional_data
data:
  confirm_destructive: true
  scope: "global"

# Reset specific kid's data
action: kidschores.reset_transactional_data
data:
  confirm_destructive: true
  scope: "kid"
  kid_name: "Sarah"

# Reset only chores for specific kid
action: kidschores.reset_transactional_data
data:
  confirm_destructive: true
  scope: "kid"
  kid_name: "Alex"
  item_type: "chores"

# Reset specific chore for all kids
action: kidschores.reset_transactional_data
data:
  confirm_destructive: true
  scope: "global"
  item_type: "chores"
  item_name: "Wash Dishes"

Use Cases:

• Monthly "Clean Slate" automation (reset counters on 1st of month)
• Seasonal reset (new school year, new chore system)
• Troubleshooting stuck states
• Kid leaving household (reset their data before archiving)

Purpose: Revoke badges from kids.

Parameters:

Flexible Targeting:

Example:

# Revoke specific badge from specific kid
action: kidschores.remove_awarded_badges
data:
  badge_name: "Perfect Week"
  kid_name: "Alex"

# Revoke badge from all kids (badge expired)
action: kidschores.remove_awarded_badges
data:
  badge_name: "Summer Challenge"

# Revoke all badges from one kid
action: kidschores.remove_awarded_badges
data:
  kid_name: "Sarah"

Use Cases:

• Seasonal badge cleanup (remove expired time-limited badges)
• Demotion logic (kid lost streak, revoke badge)
• Reset kid's badge progress after misbehavior

Purpose: Link a Kid Profile to a Parent Profile, creating a "Shadow Kid" for parent control.

Parameters:

Name Matching Requirement:

Unlinking Behavior: When unlinking, the kid is renamed to [Name]_unlinked (e.g., Mom_unlinked) to preserve history rather than deleting data.

Example:

# Link parent to kid profile
action: kidschores.manage_shadow_link
data:
  name: "Dad"
  action: "link"

# Unlink shadow kid
action: kidschores.manage_shadow_link
data:
  name: "Dad"
  action: "unlink"

Use Cases:

• Enable parents to test kid workflows
• Allow parents to claim/complete chores on behalf of kids
• Demonstration/training mode

automation:
  - alias: "Claim chore via NFC tag"
    trigger:
      - platform: tag
        tag_id: "bedroom_chore_tag"
    action:
      - action: kidschores.claim_chore
        data:
          chore_name: "Make Bed"
          kid_name: "{{ trigger.event.data.user_name }}"

→ See: Automation Example: NFC Tag Chore Claiming - Complete guide with helper sensor setup, time-based selection, and multi-kid patterns

automation:
  - alias: "Set trash chore due date from calendar"
    trigger:
      - platform: calendar
        event: start
        entity_id: calendar.trash_pickup
    action:
      - action: kidschores.set_chore_due_date
        data:
          chore_name: "Take Out Trash"
          due_date: "{{ trigger.calendar_event.start }}"

→ See: Automation Example: Calendar-Based Chore Scheduling - Detailed calendar integration patterns, lookahead windows, and multi-chore strategies

automation:
  - alias: "Apply penalty for overdue chores"
    trigger:
      - platform: state
        entity_id: sensor.sarah_kidschores_chores
        attribute: overdue_count
        to:
    condition:
      - condition: template
        value_template: "{{ state_attr('sensor.sarah_kidschores_chores', 'overdue_count') | int > 0 }}"
    action:
      - action: kidschores.apply_penalty
        data:
          kid_name: "Sarah"
          points: 5
          reason: "Overdue chore penalty"

→ See: Automation Example: Overdue Chore Penalties - Variable penalties, grace periods, escalating patterns, and forgiveness strategies

Comprehensive step-by-step guides for common automation patterns:

• NFC Tag Chore Claiming (~520 lines)

  • NFC tag setup with helper sensor configuration
  • Basic single-chore claiming pattern
  • Time-based AM/PM selection (pet feeding)
  • Multi-kid shared chore claiming
  • Troubleshooting (unknown user, button press fails, logbook issues)
  • Best practices (physical placement, tag quality, security)

• Calendar-Based Chore Scheduling (~660 lines)

  • Calendar integration setup (Google, Local, iCloud)
  • Variable weekly schedules (trash pickup example)
  • Multi-chore calendar patterns
  • Event trigger vs polling strategies
  • Lookahead window guidelines (7, 14, 21, 30+ days)
  • Debugging (event not found, date format errors)
  • Best practices (calendar organization, performance considerations)

• Overdue Chore Penalties (~500 lines)

  • Fixed penalty amounts (simple -10 points pattern)
  • Variable penalties (20% of chore points calculation)
  • Grace period implementation (30-minute buffer)
  • Escalating daily penalties (increasing: -5, -10, -20)
  • First offense forgiveness (warning → penalty pattern)
  • Debugging (penalty not applying, multiple triggers)
  • Best practices (penalty philosophy, amounts, balance with rewards)
  • Integration with completion criteria and reset overdue service

Error: not_authorized_action

• Cause: Service requires kid/parent authorization, but automation context lacks proper user
• Solution: Use admin account for automation triggers, or ensure Home Assistant user account matches kid/parent profile

Error: chore_not_found / kid_not_found

• Cause: Name parameter doesn't match any existing entity
• Solution: Check spelling (case-insensitive), verify entity exists in Configuration

Error: insufficient_points

• Cause: Kid doesn't have enough points for reward redemption
• Solution: Check sensor.kc_<kid>_points state before calling redeem_reward

Error: date_in_past

• Cause: set_chore_due_date provided a past timestamp
• Solution: Ensure due_date parameter is in the future

Error: shared_chore_kid_error

• Cause: Attempted to provide kid_name for a Shared/Shared First chore
• Solution: Remove kid_name parameter for shared chores (they use global due dates)

• Chore Advanced Features - Shared chores, multi-approval, completion criteria
• Configuration: Points System - Point economy, manual adjustments
• Configuration: Rewards - Reward redemption workflow
• Technical Reference: Services - Service implementation details, edge cases
• Dashboard: Auto-Populating UI - Dashboard button integration