Cashclaw Invoicer

CashClaw Invoicer

You handle all payment operations for CashClaw. You create invoices, generate payment links, track payment status, and send automated reminders. Every dollar earned must be tracked accurately. This is the skill that turns delivered work into collected revenue.

Prerequisites

1. Stripe account with API access enabled.
2. STRIPE_SECRET_KEY set in environment or ~/.cashclaw/config.json.
3. Node.js 18+ installed (for the stripe-ops.js script).

Install the Stripe SDK:

bashCopy code
npm install stripe

Invoice Creation

When to Invoice

• Pre-payment model: Create a payment link at ACCEPT stage. Client pays before work begins.
• Post-payment model: Create an invoice at DELIVER stage. Client pays after receiving deliverables.
• Recurring services: Create a Stripe subscription for monthly services (WhatsApp management, social media).

Invoice Data Structure

jsonCopy code
{
  "mission_id": "MISSION-20260223-001",
  "client": {
    "name": "Acme Corp",
    "email": "billing@acme.com"
  },
  "items": [
    {
      "description": "SEO Audit - Standard Tier",
      "quantity": 1,
      "unit_amount": 2900,
      "currency": "usd"
    }
  ],
  "due_date": "2026-03-02",
  "notes": "Thank you for choosing CashClaw!",
  "metadata": {
    "mission_id": "MISSION-20260223-001",
    "service": "seo-audit",
    "tier": "standard"
  }
}

Using the stripe-ops.js Script

bashCopy code
# Create a payment link
node scripts/stripe-ops.js create-link \
  --amount 2900 \
  --currency usd \
  --description "SEO Audit - Standard" \
  --mission "MISSION-20260223-001"

# Create a full invoice
node scripts/stripe-ops.js create-invoice \
  --email "billing@acme.com" \
  --amount 2900 \
  --currency usd \
  --description "SEO Audit - Standard" \
  --due-days 7

# Check payment status
node scripts/stripe-ops.js check-status \
  --invoice "in_1234567890"

# Send payment reminder
node scripts/stripe-ops.js send-reminder \
  --invoice "in_1234567890" \
  --template "gentle"

Using Stripe API Directly (curl)

If the script is unavailable, use curl with the Stripe API:

bashCopy code
# Create a customer
curl https://api.stripe.com/v1/customers \
  -u "$STRIPE_SECRET_KEY:" \
  -d "email=client@example.com" \
  -d "name=Client Name" \
  -d "metadata[mission_id]=MISSION-20260223-001"

# Create an invoice item
curl https://api.stripe.com/v1/invoiceitems \
  -u "$STRIPE_SECRET_KEY:" \
  -d "customer=cus_xxxxx" \
  -d "amount=2900" \
  -d "currency=usd" \
  -d "description=SEO Audit - Standard Tier"

# Create and send the invoice
curl https://api.stripe.com/v1/invoices \
  -u "$STRIPE_SECRET_KEY:" \
  -d "customer=cus_xxxxx" \
  -d "collection_method=send_invoice" \
  -d "days_until_due=7" \
  -d "auto_advance=true"

# Finalize the invoice
curl -X POST https://api.stripe.com/v1/invoices/in_xxxxx/finalize \
  -u "$STRIPE_SECRET_KEY:"

# Send the invoice
curl -X POST https://api.stripe.com/v1/invoices/in_xxxxx/send \
  -u "$STRIPE_SECRET_KEY:"

# Create a payment link (one-time)
curl https://api.stripe.com/v1/payment_links \
  -u "$STRIPE_SECRET_KEY:" \
  -d "line_items[0][price_data][currency]=usd" \
  -d "line_items[0][price_data][product_data][name]=SEO Audit" \
  -d "line_items[0][price_data][unit_amount]=2900" \
  -d "line_items[0][quantity]=1"

# Check invoice status
curl https://api.stripe.com/v1/invoices/in_xxxxx \
  -u "$STRIPE_SECRET_KEY:"

# List unpaid invoices
curl "https://api.stripe.com/v1/invoices?status=open&limit=100" \
  -u "$STRIPE_SECRET_KEY:"

Payment Reminder Flow

Automated reminders follow this exact schedule:

Day 0: Invoice Sent

Copy code
Subject: Invoice #{number} from {Business Name}

Hi {name},

Please find your invoice for {service} attached.

Amount: {currency} {amount}
Due Date: {due_date}

Pay now: {payment_link}

Thank you for your business!

Best,
{Business Name}

Day 3: Gentle Reminder

Only send if invoice is still unpaid.

Copy code
Subject: Friendly reminder: Invoice #{number}

Hi {name},

Just a quick reminder that invoice #{number} for {amount} is
due on {due_date}.

You can pay securely here: {payment_link}

If you have already paid, please disregard this message.

Thanks!
{Business Name}

Day 7: Follow-up

Copy code
Subject: Invoice #{number} - Payment due

Hi {name},

Your invoice #{number} for {amount} is now past due.

We would appreciate it if you could process payment at your
earliest convenience: {payment_link}

If there is an issue with the invoice or you need to discuss
payment arrangements, please let us know.

Best regards,
{Business Name}

Day 14: Final Notice

Copy code
Subject: Final notice: Invoice #{number} overdue

Hi {name},

This is our final reminder regarding invoice #{number} for
{amount}, which is now 14 days past due.

Please process payment immediately: {payment_link}

If we do not receive payment or hear from you within 48 hours,
we may need to pause any ongoing services.

If there are any issues, please reach out so we can work
something out.

Regards,
{Business Name}

Reminder Rules

1. Never send more than 1 reminder per day.
2. Stop reminders immediately once payment is received.
3. If client responds to a reminder, pause automation and handle personally.
4. After Day 14 with no response, escalate to operator -- do not send more reminders.
5. Track all reminder events in ~/.cashclaw/ledger.jsonl.

Multi-Currency Support

Supported currencies and their Stripe codes:

Important: Stripe uses the smallest currency unit (cents, pence, etc.). Always multiply the display amount by 100 before sending to Stripe.

Currency Detection

• Default to USD unless client specifies otherwise.
• Detect from client's location or previous invoices.
• Always confirm currency with client before invoicing.

Payment Tracking

Ledger Entry Format

Every payment event is logged to ~/.cashclaw/ledger.jsonl:

jsonCopy code
{"ts":"2026-02-23T12:00:00Z","event":"invoice_created","mission_id":"MISSION-20260223-001","invoice_id":"in_xxx","amount":2900,"currency":"usd"}
{"ts":"2026-02-23T12:01:00Z","event":"invoice_sent","mission_id":"MISSION-20260223-001","invoice_id":"in_xxx"}
{"ts":"2026-02-23T14:30:00Z","event":"payment_received","mission_id":"MISSION-20260223-001","invoice_id":"in_xxx","amount":2900,"currency":"usd","payment_id":"pi_xxx"}

Dashboard Update

After every payment event, update ~/.cashclaw/dashboard.json:

jsonCopy code
{
  "pending_payments": [
    {
      "invoice_id": "in_xxx",
      "mission_id": "MISSION-20260223-001",
      "amount": 2900,
      "currency": "usd",
      "status": "open",
      "due_date": "2026-03-02",
      "reminder_stage": 0
    }
  ],
  "recent_payments": [
    {
      "invoice_id": "in_yyy",
      "amount": 900,
      "currency": "usd",
      "paid_at": "2026-02-22T10:00:00Z"
    }
  ]
}

Refund Handling

If a client requests a refund:

1. Verify the original payment in Stripe.
2. Determine refund type:
   • Full refund: Client unhappy with deliverable. Process immediately.
   • Partial refund: Scope reduced or partial delivery. Calculate pro-rata.
3. Process via Stripe:

bashCopy code
# Full refund
curl https://api.stripe.com/v1/refunds \
  -u "$STRIPE_SECRET_KEY:" \
  -d "payment_intent=pi_xxxxx"

# Partial refund
curl https://api.stripe.com/v1/refunds \
  -u "$STRIPE_SECRET_KEY:" \
  -d "payment_intent=pi_xxxxx" \
  -d "amount=1500"

4. Log the refund event in the ledger.
5. Update mission status to refunded.
6. Send confirmation to client.

Recurring Billing

For monthly services (WhatsApp Manager, Social Media):

bashCopy code
# Create a product
curl https://api.stripe.com/v1/products \
  -u "$STRIPE_SECRET_KEY:" \
  -d "name=Social Media Management - Monthly Full" \
  -d "metadata[service]=social-media" \
  -d "metadata[tier]=monthly-full"

# Create a recurring price
curl https://api.stripe.com/v1/prices \
  -u "$STRIPE_SECRET_KEY:" \
  -d "product=prod_xxxxx" \
  -d "unit_amount=4900" \
  -d "currency=usd" \
  -d "recurring[interval]=month"

# Create a subscription
curl https://api.stripe.com/v1/subscriptions \
  -u "$STRIPE_SECRET_KEY:" \
  -d "customer=cus_xxxxx" \
  -d "items[0][price]=price_xxxxx"

Error Handling

Never expose raw Stripe error messages to clients. Translate them to human-friendly messages.

Example Commands

bashCopy code
# Create and send an invoice
cashclaw invoice --client "billing@acme.com" --amount 29 --service "SEO Audit" --due 7

# Check all unpaid invoices
cashclaw invoice --list --status unpaid

# Send reminders for overdue invoices
cashclaw invoice --remind --overdue

# Process a refund
cashclaw invoice --refund --invoice "in_xxxxx" --amount 29