Cashclaw Invoicer

Invoice Data Structure

{
  "mission_id": "MISSION-20260223-001",
  "client": {
    "name": "Acme Corp",
    "email": "[email protected]"
  },
  "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

# 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 "[email protected]" \
  --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:

# Create a customer
curl https://api.stripe.com/v1/customers \
  -u "$STRIPE_SECRET_KEY:" \
  -d "[email protected]" \
  -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

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.

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

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

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:

{"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:

{
  "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:

# 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):

# 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

# Create and send an invoice
cashclaw invoice --client "[email protected]" --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