CartThrob Invoice Version 1.0103

Overview

CartThrob Invoice lets you create invoices in the ExpressionEngine control panel, send invoice emails, and let customers add invoices directly to cart for checkout.

In 1.0103 code:

• invoices are stored in cartthrob_invoice_table
• invoice settings/templates are stored in cartthrob_invoice_settings
• invoice pay links/forms route through CartThrob add_to_cart_action
• paid invoices are marked during cartthrob_on_authorize

Requirements

From bundled docs in this release package:

• ExpressionEngine 2.5+
• CartThrob 2.2+
• PHP 5.3+

Installation

1. Upload /system/expressionengine/third_party/cartthrob_invoice/.
2. Install CartThrob Invoice from the Add-ons page.
3. Open Invoice CP and run Installation to install the bundled invoices template group.
4. Configure Settings before sending invoices.

Upgrading

1. Upload the updated cartthrob_invoice folder over existing files.
2. Run add-on updates in EE Add-ons.
3. Recheck Invoice Settings template selections and admin email.

Start Here (10-Minute Setup)

1. Open Add-ons > CartThrob Invoice > Settings.
2. Set:

- Invoice Administrator Email Address - Invoice Email Template - Invoice Update Email Template - Payment Reminder Email Template - Cancellation Email Template - Invoice Paid Email Template 3. Open Add and create one invoice with: - project title - total cost - status pending - customer email address 4. Save and go to View. 5. Click Send for the invoice. 6. In the email/template output, use the invoice pay link (purchase_invoice_link) and complete checkout. 7. Confirm invoice status becomes paid after authorization.

Common Tasks With Examples

1. Send A New Invoice

• Create invoice in Add.
• In View, click Send.
• Customer receives template from template_send.

2. Send Reminder Or Update

• In View, click Remind or Update.
• Reminder uses template_remind.
• Update uses template_update.

3. Cancel Invoice

• In View, click Cancel.
• On delete confirmation page, keep delete checked and submit.
• Cancellation email is sent via template_cancel before deletion path completes.

4. Print Invoice

• In View, click Print.
• Opens rendered template (uses template_send in current implementation) in a new tab.

Quick Links For Existing Users

• Need invoice grid/actions: see Invoice List (View)
• Need settings fields: see System Settings
• Need status/update behavior: see Notifications and Invoice Lifecycle
• Need tag details: see Template Tags

Control Panel Reference

Base module path: C=addons_modules&M=show_module_cp&module=cartthrob_invoice

Navigation

Main CP methods:

• system_settings
• view
• add
• edit
• delete
• installation

System Settings

Route method: system_settings

Fields:

1. Order Channel Invoice ID field (order_channel_invoice_id_field)

- Select field key used to store invoice id on the order.

2. Invoice Administrator Email Address (admin_email_address)

- Sender/from and admin recipient for invoice events.

3. Invoice Email Template (template_send)

- Default: invoices/email_send

4. Invoice Update Email Template (template_update)

- Default: invoices/email_update

5. Payment Reminder Email Template (template_remind)

- Default: invoices/email_remind

6. Cancellation Email Template (template_cancel)

- Default: invoices/email_cancel

7. Invoice Paid Email Template (template_paid)

- Default: invoices/email_paid

Add Invoice

Route method: add

Form fields:

• Project Title (inv_title)
• Total Cost (inv_cost)
• Total Hours (inv_total_hours)
• Status (inv_status) : options are pending, in_progress, paid, closed, canceled
• Project Description (inv_description)
• Member ID (inv_member_id)
• Reference Number (inv_reference_number)
• address block: : inv_first_name, inv_last_name, inv_email_address, inv_phone, inv_company, inv_address, inv_address2, inv_city, inv_state, inv_zip, inv_country_code
• line items matrix (inv_line_items) : columns item_title, item_description, hours, item_cost

Submit action: add_invoice

Behavior:

• new invoices set inv_date to current timestamp
• invoice record is written via invoices_model->update()

Edit Invoice

Route method: edit

Same core fields as Add, plus:

• hidden id
• Order ID (inv_order_id)

Submit action: add_invoice

Behavior:

• when status changes to paid, inv_paid_date is set (if not already set)
• if status is not paid, inv_paid_date is cleared (NULL)

Invoice List (View)

Route method: view

Filter form:

• filter_status dropdown
• statuses plus blank option (--)

Table columns:

1. ID
2. Title
3. Cost
4. Total Hours
5. Created
6. Paid
7. Order ID
8. Member ID
9. Status
10. Actions

Row actions:

• Edit -> opens edit for invoice id
• Cancel -> opens delete confirmation for invoice id
• Print -> opens print_invoice in new tab/window
• Send -> executes notify_action
• Update -> executes update_action
• Remind -> executes remind_action

Delete Invoice

Route method: delete

Form behavior:

• shows delete checkbox (delete=yes, checked by default)
• submits through form_update

Additional behavior in form_update:

• on delete path, attempts cancellation email (template_cancel) before record update/delete handling

Installation Utility

Routes:

• installation
• do_installation

Behavior:

• reads installer package definitions from installer/installer.xml
• installs selected template groups/templates
• bundled template group: invoices
• bundled templates: : index, email_send, email_update, email_remind, email_cancel, email_paid

Notifications and Invoice Lifecycle

Extension Hooks Registered

From updater hook list:

• cartthrob_on_authorize
• cartthrob_addon_register
• cartthrob_add_to_cart_end
• cartthrob_add_to_cart_start

Add-To-Cart Invoice Flow

1. Invoice link/form provides encoded INV value.
2. cartthrob_add_to_cart_start decodes INV and prepares POST data.
3. Validations:

- prevents same invoice being added multiple times - blocks already paid invoices 4. Injects cartthrob add-to-cart POST values: - price (PR) - title - one-time fee (OTF) - no-tax (NTX) - no-shipping (NSH) 5. cartthrob_add_to_cart_end stores invoice id in item meta invoice_number.

Payment Authorization Flow

On cartthrob_on_authorize:

• invoice items in cart are detected by invoice_number meta
• invoice row is updated:
• inv_status = paid
• inv_member_id = current member
• inv_order_id = order entry id
• inv_paid_date = now
• paid email template (template_paid) can be sent to admin and customer
• if order_channel_invoice_id_field is configured, order is updated with invoice id

Email Actions

CP actions and default templates:

• notify_action -> template_send
• update_action -> template_update
• remind_action -> template_remind
• delete path in form_update -> template_cancel
• authorize hook -> template_paid

Note:

• update_action custom event lookup uses _send_reminder suffix in code, even though the action is update.

Template Tags

Tags are used through CartThrob tag namespace in this release package:

• {exp:cartthrob:invoice}
• {exp:cartthrob:invoice_items}
• {exp:cartthrob:purchase_invoice_form}
• {exp:cartthrob:purchase_invoice_link}

invoice

Outputs one invoice record.

Parameters:

• invoice_number (string/int)
• invoice_id (alias for invoice number)

Variables:

• all scalar invoice table columns, including:
• id
• inv_description
• inv_title
• inv_cost (formatted with number library)
• inv_total_hours
• inv_status
• inv_date
• inv_paid_date
• inv_email_address
• inv_member_id
• inv_order_id
• inv_reference_number
• inv_first_name
• inv_last_name
• inv_company
• inv_address
• inv_address2
• inv_city
• inv_state
• inv_zip
• inv_country_code
• inv_phone
• added aliases:
• invoice_number
• invoice_id

Conditionals:

• {if no_results}...{/if} when invoice is missing/invalid

invoice_items

Loops line items for one invoice.

Parameters:

• invoice_number
• invoice_id (alias)

Variables:

• item_title
• item_description
• hours
• item_cost
• invoice_count (1-based row index)
• invoice_total_results (total line-item count)

Conditionals:

• {if no_results}...{/if} for missing/empty items

purchase_invoice_form

Outputs a CartThrob add-to-cart form configured for invoices.

Parameters:

• invoice_number (required)
• invoice_id (alias)
• return (optional)
• language (optional)
• additional CartThrob add-to-cart params are passed through

Behavior:

• sets hidden INV token
• posts to CartThrob add_to_cart_action

purchase_invoice_link

Outputs direct URL to add invoice to cart.

Parameters:

• invoice_number (required)
• invoice_id (alias)
• return (optional return path)

Behavior:

• builds URL with CartThrob ACT id
• encodes invoice token in INV

Changelog

Release baseline for this documentation pass:

Version 1.0103

Version note:

• Live docs page headline shows 1.013; this documentation targets 1.0103.