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 for monthly subscriptions only.
For yearly paid subscriptions, the integration creates the subscription in HaloPSA, but the recurring invoice line must be created manually.
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.
Azure Reserved Instances are not supported at this time.
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 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 In Configuration, go to the Agents permissions tab and make sure the selected agent has the following permissions enabled.
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
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.
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
In the connection modal, enter the following details from your HaloPSA account:
Site*: Your HaloPSA URL (Configuration → Integrations → HaloPSA API → Resource Server).
Client ID*: (Configuration → Integrations → HaloPSA API → View Applications → select yours → Client ID).
Client Secret*: key generated and saved when creating the application in HaloPSA.
Invoice generation day: define the schedule for the recurring invoice in HaloPSA for monthly recurring invoices. For example, selecting “15” will generate invoices covering the period from the 15th to the 14th of the following month.
Billing method: select pre-bill or post-bill.
Proration: enable or disable.
Mapping: Manual or Automatic. Automatic mapping allows the integration to automatically map a product that has been purchased if it finds an item in HaloPSA with the supplier SKU matching Sherweb’s SKU.
Click Test Connection. If the information is correct, you'll be redirected to your dashboard to start configuring 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.
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.
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 prevent missed or incorrect charges, the integration automatically creates a recurring invoice using the schedule date you defined during setup.
4.1.3 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 sync path than subscription products. These items don’t need proration and are invoiced at the same time Sherweb bills the partner.
Because of that, the integration doesn’t generate HaloPSA subscriptions for them. Instead, it inserts an invoice line directly into the recurring invoice, using the actual billed quantity and cost.
This process follows the same recurring invoice and invoice line behavior described in sections 4.1.2 and 4.1.3 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.
Important
Recurring invoices are created only for monthly subscriptions.
For yearly Cumulus subscriptions, the integration creates the subscription in HaloPSA, but it does not create a recurring invoice line. These subscriptions must be invoiced manually.
Azure Reserved instances are not supported yet, but support is coming soon.
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.
4. Once you’ve validated that the Sherweb data is accurate, go to the customer’s Subscriptions tab in HaloPSA. Locate the old subscription and deactivate or remove it.
5. 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 have been moved to, the new recurring invoice.
This approach ensures a smooth transition and prevents billing gaps before you scale the migration to all customers.
7. FAQ