Invoice Functions

Documentation for Invoice and Payment Management Functions

Overview

These functions manage invoices and payments for a subscription-based service, tracking and processing user payments, generating invoices, and calculating related financial metrics using Firestore.

Function Descriptions

1. create_new_invoice(user_id, subscription_frequency, date_paid, due_date, status, amount, transaction_id)

   • Creates a new invoice in the Firestore database.
   • Parameters:
     • user_id: Identifier for the user to whom the invoice belongs.
     • subscription_frequency: Billing frequency (e.g., Monthly, Annually).
     • date_paid: Date on which the payment was made.
     • due_date: Date by which the payment is due.
     • status: Current status of the invoice (e.g., pending, complete).
     • amount: Amount of the invoice.
     • transaction_id: Identifier for the transaction.
   • Returns:
     • Invoice ID if creation is successful, prints an error otherwise.

2. create_invoices_after_sale(user_id, frequency, amount, transaction_id)

   • Handles invoice creation immediately after a sale and schedules the next invoice based on the frequency.
   • Parameters:
     • Same as create_new_invoice plus handling future invoice scheduling.

3. get_payments_due_today()

   • Fetches payments that are due on the current day.
   • Returns:
     • A list of payments due.

4. get_pending_payments_by_user_id(user_id)

   • Retrieves all pending payments for a specific user.
   • Returns:
     • A list of the user’s pending payments.

5. update_invoice(invoice_id, date_paid, transaction_id)

   • Updates an invoice’s status to complete and logs the payment details.
   • Parameters:
     • invoice_id: ID of the invoice to update.
     • date_paid: The date the payment was completed.
     • transaction_id: Identifier for the transaction.

6. payment_failed_update(invoice_id)

   • Updates an invoice’s status to failed.
   • Parameters:
     • invoice_id: ID of the invoice to update.

7. calculate_monthly_recurring_revenue_and_paid_user_count()

   • Calculates the Monthly Recurring Revenue (MRR) and the count of users who have made payments.
   • Returns:
     • MRR value and the count of paid users.

8. calculate_revenue_churn_rates()

   • Calculates the Gross and Net revenue churn rates based on revenue lost from cancelled or failed payments.
   • Returns:
     • Gross and Net revenue churn rates as a percentage.

9. monthly_mrr(month_start, month_end)

   • Calculates the Monthly Recurring Revenue within a specified date range.
   • Parameters:
     • month_start: Start date of the period.
     • month_end: End date of the period.
   • Returns:
     • MRR for the specified period.

10. calculate_churn_rate()

    • Calculates the churn rate based on the number of users who have cancelled their subscriptions within a specific period compared to the number of users who paid in the previous month.
    • Returns:
      • Churn rate as a percentage.

Usage Example

# To create a new invoice after a sale
user_id = 'user123'
frequency = 'Monthly'
amount = 100
transaction_id = 'txn123'
create_invoices_after_sale(user_id, frequency, amount, transaction_id)

# To calculate monthly recurring revenue and paid user count
monthly_mrr, paid_users = calculate_monthly_recurring_revenue_and_paid_user_count()
print(f'Monthly MRR: ${monthly_mrr}, Paid Users: {paid_users}')

# To update an invoice as complete
invoice_id = 'invoice123'
date_paid = datetime.now()
update_invoice(invoice_id, date_paid, transaction_id)

These functions are essential for managing financial transactions and maintaining fiscal health within subscription-based services, facilitating the tracking, updating, and strategic analysis of user payments and subscriptions.