Views:

Table of Contents

  1. Important notes

  2. Getting Started

    2.1 HaloPSA Application Creation

    2.2 HaloPSA Configuration

    2.3 Enable the integration in Cumulus

  3. Mappings

    3.1 Product Mapping

    3.2 Organization Mapping 

    3.3 How to disable sync for a specific product

  4. How synchronization works

    4.1 How subscription products are synchronized

         4.1.1 Automatically create and update matching subscriptions in HaloPSA

         4.1.2 Automatically create recurring invoices and link them to subscriptions

         4.1.3 Change the recurring invoice used for synchronized charges  

         4.1.4 Add an invoice line linked to the HaloPSA subscription  

    4.2 How other product types are synchronized 

    4.3 How cancelled products are synchronized

  5. HaloPSA Logs

  6. Migrating to Sherweb HaloPSA integration

  7. Other Features 

    7.1 Import Retail Prices (SRP)

          7.1.1 Import SRP Prices

          7.1.2 CSV Format

          7.1.3 How the Import Works  

    7.2 Switch Proration Settings

  8. FAQ

     

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 supported for both monthly and yearly subscriptions. Monthly recurring invoices are created automatically by default. For yearly recurring invoices, enable Yearly Invoice Support in the Cumulus integration settings.

  • 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 (more details under section 6).

  • 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.

    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

        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

 

 

 

 

 

 

     e. Login Type: Select Agent,

     f. Login Credentials: select the corresponding agent ID.

Agent requirements: Before continuing, confirm that the selected agent meets both requirements below:
1. Default Team: The agent must be assigned to a Team. “No Default Team” option is not valid.
2. Permissions: The agent must have all required access levels listed below.

  • Clients: Read and Modify

  • Items: Read and Modify

  • Invoices: Read, Create, Modify, and Delete

  • Software: Read and Modify

Verify the agent setup: In HaloPSA, go to Configuration > Teams and Agents, open the agent record, and select the Details tab. Confirm that a valid team is selected in the Default Team field.

 

 

 

 

 

 

 

 

 

 

 

 

Verify the permissions: In the same agent record, select the Permissions tab and confirm that all required access levels listed above are enabled.

 

 

 

 

  1. Save

  2. 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 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 ensure the integration functions correctly, verify that the following 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

After setting up your HaloPSA connection, you’ll be taken to the mapping screen.

 

 

 

 

 

 

 

 

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 Product 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 or SKU,

  • 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:

  1. Find the product you want to map.

  2. Open the HaloPSA Item dropdown.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

      3. Select the matching product from your HaloPSA catalog.

      4. Confirm that Enable Sync is turned on, if you want the product to synchronize automatically.

      5. 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 Organization 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: Recurring invoices are created automatically for monthly subscriptions. For yearly subscriptions, enable Yearly Invoice Support in the integration settings (as shown below) before charges can be linked to recurring invoices in HaloPSA.

 

 

 

 

 

 

 

 

 

When Yearly Invoice Support is enabled, the integration creates yearly recurring invoices based on the subscription's original start date. If yearly subscriptions already exist when the setting is enabled, missing yearly recurring invoices are created automatically for supported subscriptions.

4.1.3 Change the 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.

  1. Navigate to the organization configuration page.

  2. Locate the Recurring Invoice setting.

  3. Select the recurring invoice you want the integration to use.

  4. Save your changes.

Note: If you select a different recurring invoice, the integration automatically updates synchronized charges to use the newly selected recurring invoice. Once all synchronized charges have been moved to the selected recurring invoice, any empty recurring invoice that was previously created by the integration is automatically removed. No manual cleanup is required.

 

 

 

 

 

 

 

 

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 to Sherweb HaloPSA integration

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. Other Features

7.1 Import Retail Prices (SRP) 

The Import SRP feature lets you quickly update the HaloPSA selling prices of the products you choose. The updated prices are automatically applied to all related subscriptions in HaloPSA, as well as the associated product records, ensuring your customers' invoices reflect the latest pricing without requiring manual updates to each subscription.

7.1.1 Import SRP Prices

  1. Navigate to Integrations > HaloPSA > Mappings.

  2. Click Import SRP.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

    3. In the import window, click Download template to download a pre-filled CSV containing your current mapped products and SRPs.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

    4. Update the pricing information in the CSV file.

    5. Upload the completed CSV file by dragging it into the upload area or selecting browse files.

    6. Review and correct any validation errors, if applicable.

    7. Click Upload to start the import.

7.1.2 CSV Format

The import file must include the following columns:

SKU, SRP, Currency
TEST30365E3-1-P-M-1M,368.59,CAD
SW0365BERR-Y1Y,6.00,USD

Note: Column headers are not case-sensitive. The import also accepts Price as an alternative to the SRP column name.

7.1.3 How the Import Works

When an SRP import is processed:

  • The SRP is updated for every mapped HaloPSA item whose SKU matches a row in the imported file.

  • Active subscriptions linked to those items are automatically repriced, so the updated price is reflected in the next billing cycle.

  • Products without a confirmed HaloPSA mapping are skipped automatically.

7.2 Switch Proration Settings

You can update the proration setting at any time to control how mid-cycle quantity changes are billed. Follow the steps below to turn proration on or off.

  1. In Cumulus, go to Integrations and open the HaloPSA integration.

  2. Open the integration settings.

     

     

     

     

     

     

     

     

     

     

     

     

     

     

     

  3. Locate the Proration setting.

  4. Turn proration on to adjust invoice amounts when quantities change during a billing cycle, or turn it off if you do not want mid-cycle adjustments.

     

     

     

     

     

     

     

     

     

     

     

     

     

     

     

     

     

     

     

     

     

     

     

     

     

     

     

     

     

     

  5. Save your changes.

Important: The updated setting applies only to future subscription changes and billing activity. Previously processed invoices and billing events are not changed.

8. FAQ

1. Does the HaloPSA integration support yearly subscriptions?

Yes. The HaloPSA integration supports recurring invoices for both monthly and yearly subscriptions. Monthly recurring invoices are created automatically by default.

For yearly recurring invoices, enable Yearly Invoice Support in the Cumulus integration settings. Once enabled, the integration uses each subscription’s original start date to create the recurring invoice. It also creates any missing recurring invoices for existing supported yearly 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.

Following a successful connection test, the integration status is automatically refreshed to reflect the updated credentials.

4. Can I change the recurring invoice used by HaloPSA integration?

Yes. You can select the monthly or yearly HaloPSA recurring invoice used for synchronized charges. If you select a different invoice, the integration automatically moves the existing synchronized line items to it.

5. Why can't I see products or organizations when configuring mappings?

The integration requires specific HaloPSA application and agent requirements to retrieve mapping data. If these requirements are not met, product, customer, or organization information may be unavailable until the issue is resolved. 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 can be synchronized to HaloPSA recurring invoices. When an existing synchronized Azure RI charge is updated, the integration updates the corresponding recurring invoice line instead of creating a new recurring line for each billing period.

7. What should I do if I accidentally delete a HaloPSA subscription created by Sherweb?

The integration can automatically recover supported deletion scenarios involving subscriptions, recurring invoices, invoice line.

If you accidentally delete one of these records, you can trigger a Resync for the affected organization (or run a general resync) to recreate missing entities without waiting for the next synchronization event. If no resync is triggered, the integration will attempt to recover the deleted entities automatically when the next synchronization event is processed.

If the affected record is not recovered after a resync or a subsequent synchronization event, 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.

You can also use the Import SRP feature to update selling prices in bulk.

  1. In Cumulus, go to Integrations > HaloPSA > Mappings.

  2. Select Import SRP.

  3. Download the CSV template and update the selling prices for the products you want to change.

  4. Upload the completed CSV file.

The integration updates matching HaloPSA item prices and reprices active subscriptions for the next billing cycle—no manual subscription updates required.

For file requirements and instructions, see 7.1 Import Retail Prices (SRP).

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.

10. Can I disable the HaloPSA integration?

Yes. You can disable the integration at any time from the HaloPSA integration settings in Cumulus.

Follow these steps:

  1. In Cumulus, go to Integrations and open the gear icon on the top right.

  2. Select Disable Integration from the menu.

 

 

 

 

 

 

 

 

 

 

     3. Review the information in the confirmation message carefully.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

     4. Select Disable Integration to confirm.

        What happens after you disable it: Cumulus will stop sending new subscription and billing updates to HaloPSA. You can enable the integration again at any time from the same settings page.