1. Important notes
Make sure your HaloPSA URL and API credentials are valid before connecting the integration.
Synchronization begins once your product mappings and organization mappings are completed and sync is enabled.
Unit Cost is synchronized to HaloPSA automatically.
Unit Price is pulled from your HaloPSA item, so make sure the price of the items is correct in HaloPSA.
Recurring invoices are created automatically for monthly subscriptions. For yearly subscriptions, enable the yearly invoice support in the integration setting in Cumulus to create also yearly recurring invoices.
Azure Reserved Instance charges are supported and can be synchronized to HaloPSA recurring invoices.
If you are switching from another vendor integration, be sure to disable the previous integration to avoid duplicate updates and disable previous recurring invoices.
Synchronization behavior may vary depending on the product type
2. Getting Started
2.1 HaloPSA Application Creation
To begin, register a new application for the HaloPSA API
1. Log in to your HaloPSA account.
2. Open Configuration in the left menu, then
a) select HaloPSA API under Integrations, or b) search "Halo" to find the feature quickly.
3. Click View Applications.
4. then select + New in the top-right corner.
4.a. Fill in the Details as shown below:
1. Provide an Application Name,
2. Description and
3. Choose Client ID and Secret (services) under Authentication Method.
4. Copy and Save the Client ID and Secret keys.
5. Login Type: Agent, Client or Supplier.
6. Login Credentials: select the correct ID.
Important: The agent selected must have the following permissions:
Client Access Level: Read and Modify
Items Access Level: Read and Modify
Invoice Access Level: Read, Create, Modify, and Delete
Software Access Level: Read and Modify
To check permissions for your agent, go to Configuration then teams and agent and go to the permissions tab.
7. Save.
8. A notification will appear indicating that no permissions were chosen for this application. Select Ok to continue.
9. Click Edit and ensure the application has at least the following privileges enabled.
Read: customers
Edit: customers
Read: items
Edit: items
Read: invoices
Edit: Invoices
Read: softwarelicensing
Edit: softwarelicensing
After you finish, scroll down to the bottom and SAVE your application.
Important: The integration requires the appropriate HaloPSA application and agent permissions to retrieve customers, products, and other data used for mapping and synchronization. If the required permissions are not granted, some mapping lists may be unavailable, and synchronization may not function as expected. The integration helps identify missing permissions and displays guidance when access issues are detected.
2.2 HaloPSA configuration
To have proper behavior with our integration, we need to ensure that some settings are enabled.
Open HaloPSA → Configuration → Billing → Recurring Invoices, (or type Recurring in the search bar) and confirm the following options are selected:
Quantities and Pro-Rata:
Allow negative pro-rata quantities
Make recurring invoice lines inactive when subscriptions or licenses become inactive
Important: Do not uncheck the ones that are selected by default.
2.3 Enable the integration in Cumulus
Once HaloPSA is configured, you can enable the integration in Cumulus.
1. Log in to your Cumulus account
2. Click Integrations in the sidebar
3. Select Connect for HaloPSA
A guided setup modal opens for HaloPSA. Complete each step to configure and test the integration.
Step 1: Enter your HaloPSA connection details
Enter your HaloPSA URL, Client ID, and Client Secret. You can find these in HaloPSA under Configuration > Integrations > HaloPSA API. Click Next when all required fields are complete.
Step 2: Configure Billing settings
Select the settings that define how billing information is created and updated in HaloPSA.
Billing method: Choose when billing should happen — Pre-billed if customers are billed in advance, or Post-billed if customers are billed after the service period.
Invoice generation day: Choose the day each monthly invoice period starts.
Proration: Enable this if invoice amounts should adjust when quantities change mid-cycle.
Step 3: Configure integration settings
Choose additional options:
Yearly invoice support: Enable this if you want yearly subscription charges linked to recurring invoices.
Automatic Product Mapping: Enable this to map products automatically when the HaloPSA Supplier SKU matches the Sherweb SKU.
When ready, click Test Connection. If the connection is successful, you’ll be redirected to your dashboard to start configuring your product and organization mappings.
3. Mappings
On the Mappings page, you will be able to ensure all product and organization mapping, as well as synchronization are up to date. Navigate through products or organization mapping using the tabs available.
3.1 Products Mapping
Here’s what each column means:
Cumulus Product: the product purchased or updated in Cumulus.
HaloPSA Item: the matching product in your HaloPSA item catalog.
Enable Sync: automatically turns on when a product is mapped, but you can turn it off if needed.
Status: shows the current mapping status for the product.
Mapped – Product is mapped and synchronization is enabled.
Auto-Mapped – Product was automatically mapped using Supplier SKU matching.
Sync Disabled – Product is mapped, but synchronization is disabled.
Not Mapped – Product has not yet been mapped to a HaloPSA item.
Error – The integration detected an issue that requires attention
To help you find products more easily, you can:
use the search bar to search by product name,
apply filters by product name or status,
sort the list to show unmapped, mapped, disabled, or error items first
Once you understand the information shown on the page, the next step is to map your products.
A) Automatic product mapping based on Supplier SKU
When enabled, the system compares the Supplier SKU of products in your PSA with Sherweb’s product SKUs.
If an exact match is found, the product is automatically mapped and its status changes to Auto-Mapped - no manual action required.
B) Manual Mapping
For each Cumulus product:
Find the product you want to map.
Open the HaloPSA Item dropdown.
Select the matching product from your HaloPSA catalog.
Confirm that Enable Sync is turned on, if you want the product to synchronize automatically.
Save your changes.
Once saved, the status will switch to “Mapped” and turn green.
If you need to refresh the HaloPSA item list, click the refresh icon in the HaloPSA Item field. Otherwise, the list refreshes automatically whenever you open or refresh the page.
After your product mappings are complete, you can move on to mapping your organizations.
3.2 Organizations Mapping
Next, go to the Organization tab and map each Cumulus organization to its corresponding HaloPSA client.
1. Find the organization you want to map.
2. Open the HaloPSA Client dropdown.
3. Select the matching customer from HaloPSA.
4. Confirm that synchronization is turned on, if you want the organization to synchronize automatically.
5. Save your changes.
Once saved, the status will switch to “Mapped” and turn green.
3.3 How to disable sync for a specific product
To disable sync for a specific product, go to Organization Mapping and click the pencil icon on the right.
This opens the list of charges for that organization, where you can disable sync for specific charges as needed.
4. How synchronization works
Synchronization starts as soon as your products and organizations are mapped, and sync is enabled. The first time the integration runs, it performs an initial synchronization to create the starting subscription quantities and billing data in HaloPSA.
4.1 How subscription products are synchronized
When a subscription product is created in Cumulus (as shown above) the integration will:
4.1.1 Automatically create and update matching subscriptions in HaloPSA
Once the data has been successfully sent to your HaloPSA instance, log in to HaloPSA and open the corresponding customer record. From the customer details page, navigate to the Subscriptions tab.
There, you will see a newly created subscription that matches the purchase made in Cumulus. The subscription includes key details such as the product name, billing cycle and term, quantity, unit price (from your HaloPSA item),
and cost price — all automatically populated by the integration.
To review changes over time, click the subscription name and open the Change History tab. This tab provides a record of subscription updates, including quantity changes, timing, and other adjustments.
4.1.2 Automatically create recurring invoices and link them to subscriptions
To simplify billing and help prevent missed or incorrect charges, the integration automatically creates recurring invoices based on the schedule date defined during setup.
IMPORTANT: Automatic recurring invoices are only created for monthly subscriptions. For yearly subscriptions, you will have to enable yearly invoice support in the integration settings in Cumulus before charges can be linked to recurring invoices in HaloPSA.
4.1.3
4.1.3 4.1.3 Change the monthly recurring invoice used for synchronized charges
After completing your organization mapping, you can choose which HaloPSA recurring invoice the integration should use for synchronized charges. This is useful if you want charges to be added to a specific recurring invoice instead of the one created automatically by the integration.
Navigate to the organization configuration page.
Locate the Recurring Invoice setting.
Select the recurring invoice you want the integration to use.
Save your changes.
Note: If you select a different recurring invoice, the integration automatically updates synchronized charges to use the newly selected recurring invoice whenever possible.
4.1.4 Add an invoice line linked to the HaloPSA subscription
When you open the recurring invoice in HaloPSA, you will see a line item for the product you mapped in Cumulus. The quantity on that line matches the subscription created by the integration.
This invoice line is updated automatically when the subscription changes, helping ensure proration is applied correctly based on your recurring invoice schedule (if proration is enabled).
Once the subscription, recurring invoice, and invoice lines are created, any quantity change made in Cumulus triggers an update event in HaloPSA.
To review the change, click the invoice ID and open the History tab. There, you can see when the change was made, what was updated, and who made the update, etc.
In case proration is enabled, if the quantity changes after the purchase date, a prorated entry is added to the invoice line linked to the subscription. This line reflects the updated quantity and the correct prorated amount based on your recurring invoice schedule.
4.2 How other product types are synchronized
Vendor‑billed, usage‑based, and one‑time purchase items follow a different synchronization model.
Since proration is not required and billing occurs only after Sherweb issues an invoice, these products do not create HaloPSA subscriptions. Instead, an invoice line is added directly to the recurring invoice, reflecting the billed quantity and
associated cost.
This process follows the same recurring invoice and invoice line behavior described in sections 4.1.2 and 4.1.4, but without linking them to subscriptions.
4.3 How cancelled products are synchronized
A subscription cancellation occurs when a subscription quantity is set to 0 or the subscription is manually cancelled. When this happens, the integration updates the corresponding HaloPSA subscription to reflect the cancellation. The associated recurring invoice line is automatically given an end date, ensuring that only the period during which the service was active is invoiced.
5. HaloPSA Logs
The Logs section provides visibility into all synchronization events sent from Cumulus to HaloPSA.
This information is useful for troubleshooting, auditing activity, and reconciliation purposes.
Logs can be filtered by: Product, Organization and Date range.
The events can display these statuses:
Success: The event was processed successfully in HaloPSA.
Failed: The event could not be completed. Review the log details to identify the issue.
Pending: The event has been received and is waiting to be processed.
To view additional details, click the arrow next to the log entry, and a small page will appear on the right where you can find more details such as invoice ID, Unit Cost, Quantity, Effective date and more.
6. Migrating from HaloPSA Integration with Other Vendors
Preparation
Treat the migration from the legacy Sherweb HaloPSA integration to the new native integration as a structured PSA data-migration project.
This means:
planning the cutover carefully,
mapping all billing‑related records,
confirming that subscriptions align correctly
and briefly running both integrations in parallel to ensure there are no billing discrepancies.
The new integration is significantly more automated and operates in near real‑time, with events typically appearing in HaloPSA within 10 to 15 minutes. As a result, it’s important to ensure your existing HaloPSA configuration—Subscriptions, Recurring Invoices, and Items— is ready for the new data flow.
Beginning
Before migrating all customers, it’s best to start with a single customer to understand the amount of work required. This is especially important if your environment uses proration or has complex billing rules.
1. Configure the new Sherweb Native integration.
2. Set up the product and subscription mappings for one customer.
3. Review all entities created by the new integration and confirm that everything aligns correctly with your billing expectations:
In the customer record, you should see one new subscription for each subscription the customer uses. Each subscription should show the correct quantity and selling price.
You should also see a new recurring invoice with a line item for each subscription. Each line item should show the product name and selling price.
4. If you already have a recurring invoice that you want to keep using, open the HaloPSA integration in Cumulus, go to Organization Mapping, find the organization, and click the pencil icon. You can then select the recurring invoice you want the integration to use.
5. Once you’ve validated that the Sherweb data is accurate and everything is migrated, go to the customer’s Subscriptions tab in HaloPSA. Locate the old subscription and deactivate or remove it.
6. If the old subscription is linked to a recurring invoice, remove that invoice only after confirming that all required items and charges are already included in, or moved to the appropriate recurring invoice selected for the new integration.
This approach ensures a smooth transition and prevents billing gaps before you scale the migration to all customers.
7. FAQ
1. Does the HaloPSA integration support yearly subscriptions?
Yes. The HaloPSA integration supports both monthly and yearly subscriptions.
Monthly subscriptions are supported by default.
For yearly subscriptions, the yearly invoice support must be enabled in the integration settings in Cumulus before charges can be linked to recurring invoices in HaloPSA.
Enabling this will allow the integration to create yearly recurring invoices to track yearly paid subscriptions.
2. Can I update my HaloPSA API credentials after the integration has been configured?
Yes. You can update your HaloPSA API credentials directly from the integration settings at any time. This allows you to replace credentials that have changed, expired, or need to be rotated without requiring assistance from Sherweb. After updating the credentials, the integration validates them to ensure the required access is available.
3. What happens if my HaloPSA credentials expire?
The integration detects invalid or expired credentials and redirects you to update them. After the credentials are updated, the integration validates the connection and required permissions before synchronization resumes.
4. Can I change the recurring invoice used by HaloPSA integration?
Yes. The integration allows you to select which monthly HaloPSA recurring invoice is used for synchronized charges. If you choose a different monthly recurring invoice, the integration automatically reassigns existing synchronized line items whenever possible.
5. Why can't I see products or organizations when configuring mappings?
The integration requires specific HaloPSA application and agent permissions to retrieve mapping data. If the required permissions are missing, product, customer, or organization information may not be available until the permissions are corrected. The integration displays warnings when permission-related issues are detected.
6. Are Azure Reserved Instance charges supported by the HaloPSA integration?
Yes. Azure Reserved Instance charges are supported and can be synchronized to HaloPSA recurring invoices through the integration.
7. What should I do if I accidentally delete a HaloPSA subscription created by Sherweb?
If you delete a subscription created by the Sherweb HaloPSA integration, contact Sherweb support for assistance.
8. How can I update the selling price of my items?
When creating subscription, we are pulling the selling price from your HaloPSA item. That price is then pushed as selling price in the subscription and then translated to the recurring invoice line-item price. In order to update the price, you will need to update each subscription price so that it automatically reflects the item selling price.
9. Why does the cost price pushed to HaloPSA not match the Sherweb price?
The integration receives prices from your billing events. In case of a prorated charge, the cost pushed to the PSA would be a prorated cost too.