Housekeep Process - Running Batch Billing and System Maintenance

The Housekeep process is a series of automated programs that handle batch billing, payment retries, subscription renewals, group membership verification, and data integrity checks. It runs automatically once per day but can be triggered manually when needed.

What Housekeep Does

The Housekeep process includes:

• Batch ecommerce transactions — processes orders that are marked for batch completion (orders with the readyForBatchComplete flag)
• Payment retries — retries failed automatic payments that are configured for retry
• Subscription renewals — creates renewal orders for subscriptions whose charged-through date has passed
• Group membership verification — verifies that group memberships align with subscription and membership status
• Data integrity checks — cleans up and verifies data consistency across accounts, orders, and transactions
• GL data exports — runs automatic GL exports if configured (Format 1/DLI only)

The tool description reads: "This tool runs the Housekeep Process, a series of programs that includes processing batch ecommerce transactions and verifying data integrity. Housekeep runs automatically each day so run this tool manually only if you need to force it to run now."

Viewing Housekeep Status

Navigate to Tools > Housekeep in the Ecommerce portal to see:

• Last Run — the date and time of the most recent Housekeep execution
• Batch Enabled — whether the accounting batch is active
• Only 1 Batch Transaction — whether debugging mode is enabled (shown only when Batch Enabled is true)

The Batch Enabled Setting

This is the most important Housekeep setting. It controls whether any accounting operations occur during the Housekeep cycle.

When Batch Enabled is False:

The tool displays: "IMPORTANT: NO accounting (billing, payments, group verification, etc) will take place during the housekeep cycle. To change, go to the Billing tab of the Settings page and check the box 'Enable automatic billing during housekeep'."

With batch disabled, Housekeep still runs system cleanup and data integrity checks, but no financial transactions are processed. This means:

• Batched orders will not be completed
• Failed payments will not be retried
• Subscriptions will not be renewed
• Group memberships will not be verified against subscription status

When Batch Enabled is True:

The tool displays: "Housekeep will include both system cleanup as well as the accounting batch (billing, payments, group verification, etc) during the housekeep cycle."

All accounting operations are included in the Housekeep cycle.

To change this setting, navigate to the Settings page and open the Billing tab.

The Only 1 Batch Transaction Setting

This debugging mode is visible only when Batch Enabled is true.

When set to True:

The tool displays: "IMPORTANT: Only ONE transaction will be run during the next batch cycle. This is typically only for debugging payment processors, etc."

Only a single batched transaction is processed per Housekeep cycle. This is useful when troubleshooting payment processor issues, allowing you to verify one transaction at a time.

When set to False:

The tool displays: "All batched transactions will be run during the next batch cycle."

All pending transactions are processed normally.

To change this setting, navigate to the Settings page.

Running Housekeep Manually

Run Now (Synchronous)

Click Process Housekeep Now to run Housekeep immediately and wait for it to complete. The page will display "Housekeep Process execution complete" along with any output from the process when it finishes.

Use this when you need confirmation that the process has completed before taking further action.

Run in Background (Asynchronous)

Click Process Housekeep in Background to queue the Housekeep process for execution. The message "The Housekeep Process will run within the next 60 seconds" is displayed, and you can continue working in the portal while it runs.

Use this when you want to trigger the process but don't need to wait for results.

When to Run Housekeep Manually

Since Housekeep runs automatically each day, manual execution is typically needed only when:

• You have created batched invoices and need them processed before the next automatic cycle
• A payment processor issue has been resolved and you want to retry failed payments immediately
• Subscription renewals are pending and you want them processed without waiting
• You are testing or debugging billing configuration changes
• You have changed the Batch Enabled or Only 1 Batch Transaction settings and want to verify the results

Tips

• Always verify the Batch Enabled setting before relying on automatic billing — if it is disabled, no accounting will happen
• Use Only 1 Batch Transaction mode when troubleshooting payment processor integrations to avoid processing multiple transactions with a potentially misconfigured processor
• Check the Last Run date to verify that automatic Housekeep is executing daily as expected
• If Housekeep has not run recently, there may be an issue with the scheduled task configuration on the server